新增 API 文档
This commit is contained in:
@@ -7,8 +7,10 @@
|
||||
- 页面 使用记录
|
||||
- 代理数据表的 secret 字段 aes 加密存储
|
||||
|
||||
- 将 LocalDateTime 迁移到 orm
|
||||
- globals 合并到 services 或者反之
|
||||
- 自定义的服务错误没有必要，可以统一在 handler 层使用包装的 fiber.Error
|
||||
|
||||
- 公众号的到期提示
|
||||
- 支付回调处理
|
||||
- 保存 session 到数据库
|
||||
|
||||
413
docs/api.yaml
Normal file
413
docs/api.yaml
Normal file
@@ -0,0 +1,413 @@
|
||||
openapi: 3.1.0
|
||||
|
||||
info:
|
||||
title: platform
|
||||
description: 后端服务 API 列表
|
||||
version: 1.0.0
|
||||
|
||||
servers:
|
||||
- url: 'http://192.168.3.42:8080'
|
||||
description: 本地开发环境
|
||||
|
||||
components:
|
||||
schemas:
|
||||
PageRequest:
|
||||
type: object
|
||||
properties:
|
||||
page:
|
||||
type: integer
|
||||
description: 页码，从1开始
|
||||
default: 1
|
||||
size:
|
||||
type: integer
|
||||
description: 每页条数
|
||||
default: 10
|
||||
maximum: 100
|
||||
|
||||
PageResponse:
|
||||
type: object
|
||||
properties:
|
||||
total:
|
||||
type: integer
|
||||
description: 总记录数
|
||||
page:
|
||||
type: integer
|
||||
description: 当前页码
|
||||
size:
|
||||
type: integer
|
||||
description: 每页大小
|
||||
list:
|
||||
type: array
|
||||
description: 数据列表
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- total
|
||||
- page
|
||||
- size
|
||||
- list
|
||||
|
||||
tags:
|
||||
- name: Auth
|
||||
description: 认证授权相关接口
|
||||
- name: User
|
||||
description: 用户相关接口
|
||||
- name: Channel
|
||||
description: 通道相关接口
|
||||
- name: Whitelist
|
||||
description: 白名单相关接口
|
||||
- name: Resource
|
||||
description: 套餐资源相关接口
|
||||
- name: Bill
|
||||
description: 账单相关接口
|
||||
- name: Trade
|
||||
description: 交易相关接口
|
||||
- name: Announcement
|
||||
description: 公告相关接口
|
||||
|
||||
paths:
|
||||
|
||||
/api/auth/token:
|
||||
post:
|
||||
tags:
|
||||
- Auth
|
||||
summary: OAuth2 Token 端点
|
||||
description: 获取访问令牌，支持授权码、密码、客户端凭据、刷新令牌四种授权方式
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
grant_type:
|
||||
type: string
|
||||
description: 授权类型
|
||||
enum: [ authorization_code, password, client_credentials, refresh_token ]
|
||||
client_id:
|
||||
type: string
|
||||
description: 客户端ID
|
||||
client_secret:
|
||||
type: string
|
||||
description: 客户端密钥
|
||||
code:
|
||||
type: string
|
||||
description: 授权码（authorization_code 模式使用）
|
||||
redirect_uri:
|
||||
type: string
|
||||
description: 重定向URI（authorization_code 模式使用）
|
||||
username:
|
||||
type: string
|
||||
description: 用户名（password 模式使用）
|
||||
password:
|
||||
type: string
|
||||
description: 密码（password 模式使用）
|
||||
refresh_token:
|
||||
type: string
|
||||
description: 刷新令牌（refresh_token 模式使用）
|
||||
scope:
|
||||
type: string
|
||||
description: 权限范围
|
||||
required:
|
||||
- grant_type
|
||||
responses:
|
||||
'200':
|
||||
description: 认证成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
access_token:
|
||||
type: string
|
||||
description: 访问令牌
|
||||
refresh_token:
|
||||
type: string
|
||||
description: 刷新令牌
|
||||
expires_in:
|
||||
type: integer
|
||||
description: 过期时间（秒）
|
||||
token_type:
|
||||
type: string
|
||||
description: 令牌类型
|
||||
default: Bearer
|
||||
scope:
|
||||
type: string
|
||||
description: 授权范围
|
||||
required:
|
||||
- access_token
|
||||
- expires_in
|
||||
- token_type
|
||||
'400':
|
||||
description: 接口请求失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
error:
|
||||
type: integer
|
||||
description: 错误码
|
||||
error_description:
|
||||
type: string
|
||||
description: 错误描述
|
||||
required:
|
||||
- error
|
||||
- error_description
|
||||
|
||||
/api/auth/revoke:
|
||||
post:
|
||||
tags:
|
||||
- Auth
|
||||
summary: OAuth2 Revoke 端点
|
||||
description: 撤销访问令牌或刷新令牌
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: true
|
||||
properties:
|
||||
access_token:
|
||||
type: string
|
||||
description: 访问令牌
|
||||
required: true
|
||||
refresh_token:
|
||||
type: string
|
||||
description: 刷新令牌
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
description: 撤销成功
|
||||
content:
|
||||
text/plain:
|
||||
schema: false
|
||||
|
||||
/api/auth/introspect:
|
||||
post:
|
||||
tags:
|
||||
- Auth
|
||||
summary: OAuth2 Introspect 端点
|
||||
description: 检查令牌的有效性和相关信息
|
||||
responses:
|
||||
'200':
|
||||
description: 检查成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
|
||||
/api/auth/verify/sms:
|
||||
post:
|
||||
tags:
|
||||
- Auth
|
||||
summary: 短信验证码验证
|
||||
description: 验证短信验证码
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: true
|
||||
properties:
|
||||
purpose:
|
||||
type: string
|
||||
description: 验证码用途
|
||||
required: true
|
||||
phone:
|
||||
type: string
|
||||
description: 手机号码
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
description: 验证成功
|
||||
content:
|
||||
text/plain:
|
||||
schema: false
|
||||
|
||||
/api/user/update:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 更新用户信息
|
||||
description: 更新用户基本信息
|
||||
|
||||
/api/user/update/account:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 更新账号信息
|
||||
description: 更新用户账号相关信息
|
||||
|
||||
/api/user/update/password:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 更新密码
|
||||
description: 更新用户密码
|
||||
|
||||
/api/user/identify:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 用户身份认证
|
||||
description: 发起用户身份认证
|
||||
|
||||
/api/user/identify/callback:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 身份认证回调
|
||||
description: 身份认证回调处理
|
||||
|
||||
/api/user/recharge/prepare/alipay:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 准备支付宝充值
|
||||
description: 准备使用支付宝进行账户充值
|
||||
|
||||
/api/user/recharge/confirm/alipay:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 确认支付宝充值
|
||||
description: 确认支付宝充值结果
|
||||
|
||||
/api/user/recharge/prepare/wechat:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 准备微信充值
|
||||
description: 准备使用微信进行账户充值
|
||||
|
||||
/api/user/recharge/confirm/wechat:
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: 确认微信充值
|
||||
description: 确认微信充值结果
|
||||
|
||||
/api/channel/list:
|
||||
post:
|
||||
tags:
|
||||
- Channel
|
||||
summary: 获取通道列表
|
||||
description: 获取所有可用通道的列表
|
||||
|
||||
/api/channel/create:
|
||||
post:
|
||||
tags:
|
||||
- Channel
|
||||
summary: 创建通道
|
||||
description: 创建新的通道
|
||||
|
||||
/api/channel/remove:
|
||||
post:
|
||||
tags:
|
||||
- Channel
|
||||
summary: 删除通道
|
||||
description: 删除指定的通道
|
||||
|
||||
/api/whitelist/list:
|
||||
post:
|
||||
tags:
|
||||
- Whitelist
|
||||
summary: 获取白名单列表
|
||||
description: 获取所有白名单记录
|
||||
|
||||
/api/whitelist/create:
|
||||
post:
|
||||
tags:
|
||||
- Whitelist
|
||||
summary: 创建白名单
|
||||
description: 创建新的白名单记录
|
||||
|
||||
/api/whitelist/update:
|
||||
post:
|
||||
tags:
|
||||
- Whitelist
|
||||
summary: 更新白名单
|
||||
description: 更新指定的白名单记录
|
||||
|
||||
/api/whitelist/remove:
|
||||
post:
|
||||
tags:
|
||||
- Whitelist
|
||||
summary: 删除白名单
|
||||
description: 删除指定的白名单记录
|
||||
|
||||
/api/resource/list/pss:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 获取套餐列表
|
||||
description: 获取所有可用套餐列表
|
||||
|
||||
/api/resource/all:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 获取所有资源
|
||||
description: 获取所有可用资源信息
|
||||
|
||||
/api/resource/create/balance:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 使用余额创建资源
|
||||
description: 使用账户余额购买资源
|
||||
|
||||
|
||||
/api/resource/prepare/alipay:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 准备支付宝购买资源
|
||||
description: 准备使用支付宝购买资源
|
||||
|
||||
/api/resource/create/alipay:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 确认支付宝购买资源
|
||||
description: 确认使用支付宝购买资源
|
||||
|
||||
/api/resource/prepare/wechat:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 准备微信购买资源
|
||||
description: 准备使用微信购买资源
|
||||
|
||||
/api/resource/create/wechat:
|
||||
post:
|
||||
tags:
|
||||
- Resource
|
||||
summary: 确认微信购买资源
|
||||
description: 确认使用微信购买资源
|
||||
|
||||
/api/bill/list:
|
||||
post:
|
||||
tags:
|
||||
- Bill
|
||||
summary: 获取账单列表
|
||||
description: 获取用户账单记录列表
|
||||
|
||||
/api/trade/callback/alipay:
|
||||
post:
|
||||
tags:
|
||||
- Trade
|
||||
summary: 支付宝交易回调
|
||||
description: 处理支付宝交易回调通知
|
||||
|
||||
/api/announcement/list:
|
||||
post:
|
||||
tags:
|
||||
- Announcement
|
||||
summary: 获取公告列表
|
||||
description: 获取系统公告列表
|
||||
|
||||
|
||||
@@ -6,14 +6,7 @@ import (
|
||||
"time"
|
||||
)
|
||||
|
||||
// region req
|
||||
|
||||
type PageReqInter interface {
|
||||
GetPage() int
|
||||
GetSize() int
|
||||
GetOffset() int
|
||||
GetLimit() int
|
||||
}
|
||||
// region page
|
||||
|
||||
type PageReq struct {
|
||||
RawPage int `json:"page"`
|
||||
@@ -45,15 +38,6 @@ func (p *PageReq) GetLimit() int {
|
||||
return p.GetSize()
|
||||
}
|
||||
|
||||
// endregion
|
||||
|
||||
// region resp
|
||||
|
||||
type ErrResp struct {
|
||||
Message string `json:"message"`
|
||||
Error bool `json:"error"`
|
||||
}
|
||||
|
||||
type PageResp struct {
|
||||
Total int `json:"total"`
|
||||
Page int `json:"page"`
|
||||
@@ -144,37 +128,3 @@ func (ldt *LocalDateTime) UnmarshalJSON(b []byte) error {
|
||||
}
|
||||
|
||||
// endregion
|
||||
|
||||
// region err
|
||||
|
||||
type ServiceErr struct {
|
||||
code int
|
||||
name string
|
||||
msg string
|
||||
}
|
||||
|
||||
func (e ServiceErr) Code() int {
|
||||
return e.code
|
||||
}
|
||||
|
||||
func (e ServiceErr) Name() string {
|
||||
return e.name
|
||||
}
|
||||
|
||||
func (e ServiceErr) Error() string {
|
||||
return e.msg
|
||||
}
|
||||
|
||||
func NewErr(name, msg string, code ...int) *ServiceErr {
|
||||
_code := 400
|
||||
if len(code) > 0 {
|
||||
_code = code[0]
|
||||
}
|
||||
return &ServiceErr{
|
||||
name: name,
|
||||
msg: msg,
|
||||
code: _code,
|
||||
}
|
||||
}
|
||||
|
||||
// endregion
|
||||
|
||||
@@ -4,7 +4,6 @@ import (
|
||||
"errors"
|
||||
"gorm.io/gorm"
|
||||
"log/slog"
|
||||
"platform/web/core"
|
||||
"reflect"
|
||||
|
||||
"github.com/gofiber/fiber/v2"
|
||||
@@ -16,7 +15,6 @@ func ErrorHandler(c *fiber.Ctx, err error) error {
|
||||
var message = "服务器异常"
|
||||
|
||||
var fiberErr *fiber.Error
|
||||
var serviceErr *core.ServiceErr
|
||||
|
||||
switch {
|
||||
|
||||
@@ -25,11 +23,6 @@ func ErrorHandler(c *fiber.Ctx, err error) error {
|
||||
code = fiberErr.Code
|
||||
message = fiberErr.Message
|
||||
|
||||
// 服务错误
|
||||
case errors.As(err, &serviceErr):
|
||||
code = serviceErr.Code()
|
||||
message = serviceErr.Error()
|
||||
|
||||
// gorm 错误，忽略
|
||||
case errors.Is(err, gorm.ErrForeignKeyViolated):
|
||||
|
||||
|
||||
Reference in New Issue
Block a user