420 lines
11 KiB
YAML
420 lines
11 KiB
YAML
|
openapi: 3.1.0
|
||
|
|
info:
|
||
|
|
title: BAI PocketBase WeChat API
|
||
|
|
version: 1.0.0-wx
|
||
|
|
description: |
|
||
|
|
面向微信端的小程序接口文档。
|
||
|
|
本文档只包含微信登录、微信资料完善，以及微信端会共用的系统接口。
|
||
|
|
license:
|
||
|
|
name: Proprietary
|
||
|
|
identifier: LicenseRef-Proprietary
|
||
|
|
servers:
|
||
|
|
- url: https://bai-api.blv-oa.com
|
||
|
|
description: 生产环境
|
||
|
|
- url: http://localhost:8090
|
||
|
|
description: PocketBase 本地环境
|
||
|
|
tags:
|
||
|
|
- name: 系统
|
||
|
|
description: 微信端共用系统接口
|
||
|
|
- name: 微信认证
|
||
|
|
description: 微信登录、资料完善与 token 刷新接口
|
||
|
|
paths:
|
||
|
|
/pb/api/system/users-count:
|
||
|
|
post:
|
||
|
|
operationId: postSystemUsersCount
|
||
|
|
security: []
|
||
|
|
tags:
|
||
|
|
- 系统
|
||
|
|
summary: 查询用户总数
|
||
|
|
description: 统计 `tbl_auth_users` 集合中的记录总数。
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: 查询成功
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/UsersCountResponse'
|
||
|
|
'400':
|
||
|
|
description: 请求参数错误
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'500':
|
||
|
|
description: 服务端错误
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
/pb/api/system/refresh-token:
|
||
|
|
post:
|
||
|
|
operationId: postSystemRefreshToken
|
||
|
|
security:
|
||
|
|
- bearerAuth: []
|
||
|
|
- {}
|
||
|
|
tags:
|
||
|
|
- 系统
|
||
|
|
summary: 刷新认证 token
|
||
|
|
description: |
|
||
|
|
当当前 `Authorization` 仍有效时，直接基于当前 auth 用户续签。
|
||
|
|
当 token 失效时，可传入 `users_wx_code` 走微信 code 重新签发。
|
||
|
|
requestBody:
|
||
|
|
required: false
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/SystemRefreshTokenRequest'
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: 刷新成功
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/RefreshTokenResponse'
|
||
|
|
'400':
|
||
|
|
description: 参数错误或微信 code 换取失败
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'401':
|
||
|
|
description: token 无效，且未提供有效的 `users_wx_code`
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'404':
|
||
|
|
description: 当前用户不存在
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'415':
|
||
|
|
description: 请求体不是 JSON
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'429':
|
||
|
|
description: 请求过于频繁
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'500':
|
||
|
|
description: 服务端错误
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
/pb/api/wechat/login:
|
||
|
|
post:
|
||
|
|
operationId: postWechatLogin
|
||
|
|
security: []
|
||
|
|
tags:
|
||
|
|
- 微信认证
|
||
|
|
summary: 微信登录或首次注册
|
||
|
|
description: |
|
||
|
|
使用微信 `users_wx_code` 换取微信 openid。
|
||
|
|
若 `tbl_auth_users` 中不存在对应用户，则自动创建新 auth 用户并返回 token。
|
||
|
|
requestBody:
|
||
|
|
required: true
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/WechatLoginRequest'
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: 登录或注册成功
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/AuthSuccessResponse'
|
||
|
|
'400':
|
||
|
|
description: 参数错误或保存用户失败
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'401':
|
||
|
|
description: 认证失败
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'415':
|
||
|
|
description: 请求体不是 JSON
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'429':
|
||
|
|
description: 请求过于频繁
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'500':
|
||
|
|
description: 服务端错误
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
/pb/api/wechat/profile:
|
||
|
|
post:
|
||
|
|
operationId: postWechatProfile
|
||
|
|
security:
|
||
|
|
- bearerAuth: []
|
||
|
|
tags:
|
||
|
|
- 微信认证
|
||
|
|
summary: 更新微信用户资料
|
||
|
|
description: |
|
||
|
|
基于当前 `Authorization` 对应的 auth 用户更新昵称、手机号和头像。
|
||
|
|
requestBody:
|
||
|
|
required: true
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/WechatProfileRequest'
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: 更新成功
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/WechatProfileResponse'
|
||
|
|
'400':
|
||
|
|
description: 参数错误、手机号已被占用或资料更新失败
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'401':
|
||
|
|
description: token 无效或缺少 openid
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'415':
|
||
|
|
description: 请求体不是 JSON
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'429':
|
||
|
|
description: 请求过于频繁
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
'500':
|
||
|
|
description: 服务端错误
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/ErrorResponse'
|
||
|
|
components:
|
||
|
|
securitySchemes:
|
||
|
|
bearerAuth:
|
||
|
|
type: http
|
||
|
|
scheme: bearer
|
||
|
|
bearerFormat: JWT
|
||
|
|
schemas:
|
||
|
|
ApiResponseBase:
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- code
|
||
|
|
- msg
|
||
|
|
- data
|
||
|
|
properties:
|
||
|
|
code:
|
||
|
|
type: integer
|
||
|
|
example: 200
|
||
|
|
msg:
|
||
|
|
type: string
|
||
|
|
example: 操作成功
|
||
|
|
data:
|
||
|
|
type: object
|
||
|
|
additionalProperties: true
|
||
|
|
ErrorResponse:
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- code
|
||
|
|
- msg
|
||
|
|
- data
|
||
|
|
properties:
|
||
|
|
code:
|
||
|
|
type: integer
|
||
|
|
example: 400
|
||
|
|
msg:
|
||
|
|
type: string
|
||
|
|
example: 请求失败
|
||
|
|
data:
|
||
|
|
type: object
|
||
|
|
additionalProperties: true
|
||
|
|
CompanyInfo:
|
||
|
|
anyOf:
|
||
|
|
- type: object
|
||
|
|
additionalProperties: true
|
||
|
|
- type: 'null'
|
||
|
|
UserInfo:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
pb_id:
|
||
|
|
type: string
|
||
|
|
users_convers_id:
|
||
|
|
type: string
|
||
|
|
users_id:
|
||
|
|
type: string
|
||
|
|
users_idtype:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- WeChat
|
||
|
|
- ManagePlatform
|
||
|
|
users_id_number:
|
||
|
|
type: string
|
||
|
|
users_type:
|
||
|
|
type: string
|
||
|
|
users_name:
|
||
|
|
type: string
|
||
|
|
users_status:
|
||
|
|
type:
|
||
|
|
- string
|
||
|
|
- number
|
||
|
|
users_rank_level:
|
||
|
|
type:
|
||
|
|
- number
|
||
|
|
- integer
|
||
|
|
users_auth_type:
|
||
|
|
type:
|
||
|
|
- number
|
||
|
|
- integer
|
||
|
|
users_phone:
|
||
|
|
type: string
|
||
|
|
users_phone_masked:
|
||
|
|
type: string
|
||
|
|
users_level:
|
||
|
|
type: string
|
||
|
|
users_picture:
|
||
|
|
type: string
|
||
|
|
openid:
|
||
|
|
type: string
|
||
|
|
description: 全平台统一身份标识
|
||
|
|
company_id:
|
||
|
|
type: string
|
||
|
|
users_parent_id:
|
||
|
|
type: string
|
||
|
|
users_promo_code:
|
||
|
|
type: string
|
||
|
|
usergroups_id:
|
||
|
|
type: string
|
||
|
|
company:
|
||
|
|
$ref: '#/components/schemas/CompanyInfo'
|
||
|
|
created:
|
||
|
|
type: string
|
||
|
|
updated:
|
||
|
|
type: string
|
||
|
|
WechatLoginRequest:
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- users_wx_code
|
||
|
|
properties:
|
||
|
|
users_wx_code:
|
||
|
|
type: string
|
||
|
|
description: 微信小程序登录临时凭证 code
|
||
|
|
example: 0a1b2c3d4e5f6g
|
||
|
|
WechatProfileRequest:
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- users_name
|
||
|
|
- users_phone_code
|
||
|
|
- users_picture
|
||
|
|
properties:
|
||
|
|
users_name:
|
||
|
|
type: string
|
||
|
|
example: 张三
|
||
|
|
users_phone_code:
|
||
|
|
type: string
|
||
|
|
example: 2b7d9f2e3c4a5b6d7e8f
|
||
|
|
users_picture:
|
||
|
|
type: string
|
||
|
|
example: https://example.com/avatar.png
|
||
|
|
SystemRefreshTokenRequest:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
users_wx_code:
|
||
|
|
type:
|
||
|
|
- string
|
||
|
|
- 'null'
|
||
|
|
description: |
|
||
|
|
可选。
|
||
|
|
当前 token 失效时，可通过该 code 重新签发 token。
|
||
|
|
example: 0a1b2c3d4e5f6g
|
||
|
|
AuthSuccessData:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
status:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- register_success
|
||
|
|
- login_success
|
||
|
|
is_info_complete:
|
||
|
|
type: boolean
|
||
|
|
user:
|
||
|
|
$ref: '#/components/schemas/UserInfo'
|
||
|
|
AuthSuccessResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/ApiResponseBase'
|
||
|
|
- type: object
|
||
|
|
required:
|
||
|
|
- token
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
$ref: '#/components/schemas/AuthSuccessData'
|
||
|
|
token:
|
||
|
|
type: string
|
||
|
|
description: PocketBase 原生 auth token
|
||
|
|
WechatProfileResponseData:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
status:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- update_success
|
||
|
|
user:
|
||
|
|
$ref: '#/components/schemas/UserInfo'
|
||
|
|
WechatProfileResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/ApiResponseBase'
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
$ref: '#/components/schemas/WechatProfileResponseData'
|
||
|
|
RefreshTokenResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/ApiResponseBase'
|
||
|
|
- type: object
|
||
|
|
required:
|
||
|
|
- token
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
type: object
|
||
|
|
additionalProperties: true
|
||
|
|
example: {}
|
||
|
|
token:
|
||
|
|
type: string
|
||
|
|
description: 新签发的 PocketBase 原生 auth token
|
||
|
|
UsersCountData:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
total_users:
|
||
|
|
type: integer
|
||
|
|
example: 128
|
||
|
|
UsersCountResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: '#/components/schemas/ApiResponseBase'
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
$ref: '#/components/schemas/UsersCountData'
|