新增 API 文档
This commit is contained in:
@@ -7,8 +7,10 @@
|
|||||||
- 页面 使用记录
|
- 页面 使用记录
|
||||||
- 代理数据表的 secret 字段 aes 加密存储
|
- 代理数据表的 secret 字段 aes 加密存储
|
||||||
|
|
||||||
|
- 将 LocalDateTime 迁移到 orm
|
||||||
- globals 合并到 services 或者反之
|
- globals 合并到 services 或者反之
|
||||||
- 自定义的服务错误没有必要，可以统一在 handler 层使用包装的 fiber.Error
|
- 自定义的服务错误没有必要，可以统一在 handler 层使用包装的 fiber.Error
|
||||||
|
|
||||||
- 公众号的到期提示
|
- 公众号的到期提示
|
||||||
- 支付回调处理
|
- 支付回调处理
|
||||||
- 保存 session 到数据库
|
- 保存 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"
|
"time"
|
||||||
)
|
)
|
||||||
|
|
||||||
// region req
|
// region page
|
||||||
|
|
||||||
type PageReqInter interface {
|
|
||||||
GetPage() int
|
|
||||||
GetSize() int
|
|
||||||
GetOffset() int
|
|
||||||
GetLimit() int
|
|
||||||
}
|
|
||||||
|
|
||||||
type PageReq struct {
|
type PageReq struct {
|
||||||
RawPage int `json:"page"`
|
RawPage int `json:"page"`
|
||||||
@@ -45,15 +38,6 @@ func (p *PageReq) GetLimit() int {
|
|||||||
return p.GetSize()
|
return p.GetSize()
|
||||||
}
|
}
|
||||||
|
|
||||||
// endregion
|
|
||||||
|
|
||||||
// region resp
|
|
||||||
|
|
||||||
type ErrResp struct {
|
|
||||||
Message string `json:"message"`
|
|
||||||
Error bool `json:"error"`
|
|
||||||
}
|
|
||||||
|
|
||||||
type PageResp struct {
|
type PageResp struct {
|
||||||
Total int `json:"total"`
|
Total int `json:"total"`
|
||||||
Page int `json:"page"`
|
Page int `json:"page"`
|
||||||
@@ -144,37 +128,3 @@ func (ldt *LocalDateTime) UnmarshalJSON(b []byte) error {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// endregion
|
// 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"
|
"errors"
|
||||||
"gorm.io/gorm"
|
"gorm.io/gorm"
|
||||||
"log/slog"
|
"log/slog"
|
||||||
"platform/web/core"
|
|
||||||
"reflect"
|
"reflect"
|
||||||
|
|
||||||
"github.com/gofiber/fiber/v2"
|
"github.com/gofiber/fiber/v2"
|
||||||
@@ -16,7 +15,6 @@ func ErrorHandler(c *fiber.Ctx, err error) error {
|
|||||||
var message = "服务器异常"
|
var message = "服务器异常"
|
||||||
|
|
||||||
var fiberErr *fiber.Error
|
var fiberErr *fiber.Error
|
||||||
var serviceErr *core.ServiceErr
|
|
||||||
|
|
||||||
switch {
|
switch {
|
||||||
|
|
||||||
@@ -25,11 +23,6 @@ func ErrorHandler(c *fiber.Ctx, err error) error {
|
|||||||
code = fiberErr.Code
|
code = fiberErr.Code
|
||||||
message = fiberErr.Message
|
message = fiberErr.Message
|
||||||
|
|
||||||
// 服务错误
|
|
||||||
case errors.As(err, &serviceErr):
|
|
||||||
code = serviceErr.Code()
|
|
||||||
message = serviceErr.Error()
|
|
||||||
|
|
||||||
// gorm 错误，忽略
|
// gorm 错误，忽略
|
||||||
case errors.Is(err, gorm.ErrForeignKeyViolated):
|
case errors.Is(err, gorm.ErrForeignKeyViolated):
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user