kevin
b683fb293e
- 新增 /api/auth/register、/api/auth/login，JWT 签发与 Bearer 鉴权中间件 - notes 需登录，users/user-groups 仅管理员；auth 配置项随版本 1→2 自动补全 - internal/api 仅保留路由装配，拆分为 auth/user/usergroup/note/httpx/testutil - 同步更新 Swagger 文档与前端注册接口路径
1523 lines
53 KiB
Go
1523 lines
53 KiB
Go
// Package docs Code generated by swaggo/swag. DO NOT EDIT
|
||
package docs
|
||
|
||
import "github.com/swaggo/swag"
|
||
|
||
const docTemplate = `{
|
||
"schemes": {{ marshal .Schemes }},
|
||
"swagger": "2.0",
|
||
"info": {
|
||
"description": "{{escape .Description}}",
|
||
"title": "{{.Title}}",
|
||
"contact": {},
|
||
"version": "{{.Version}}"
|
||
},
|
||
"host": "{{.Host}}",
|
||
"basePath": "{{.BasePath}}",
|
||
"paths": {
|
||
"/auth/login": {
|
||
"post": {
|
||
"description": "使用用户名或邮箱登录，成功返回 JWT（有效期见 auth.token_ttl）与用户信息。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"auth"
|
||
],
|
||
"summary": "Login",
|
||
"parameters": [
|
||
{
|
||
"description": "登录凭证",
|
||
"name": "credentials",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/auth.LoginRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/auth.LoginResponse"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "账号或密码错误",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/auth/register": {
|
||
"post": {
|
||
"description": "公开注册，创建普通用户并默认加入普通用户组（id 1）。username 长度 3-50 且唯一，email 唯一，password 长度 6-72。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"auth"
|
||
],
|
||
"summary": "Register",
|
||
"parameters": [
|
||
{
|
||
"description": "注册信息",
|
||
"name": "user",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/auth.RegisterRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"201": {
|
||
"description": "Created",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.User"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "用户名或邮箱已存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/health": {
|
||
"get": {
|
||
"description": "检查服务与数据库连接状态；数据库不可用时返回 503。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"system"
|
||
],
|
||
"summary": "Health check",
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/api.HealthResponse"
|
||
}
|
||
},
|
||
"503": {
|
||
"description": "Service Unavailable",
|
||
"schema": {
|
||
"$ref": "#/definitions/api.HealthResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/notes": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "分页查询便签列表，按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"notes"
|
||
],
|
||
"summary": "List notes",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "页码，默认 1",
|
||
"name": "page",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"type": "integer",
|
||
"example": 20,
|
||
"description": "每页数量，默认 20，最大 100",
|
||
"name": "page_size",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/note.ListResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "创建便签。title 必填且最长 200 字符，content 可选。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"notes"
|
||
],
|
||
"summary": "Create a note",
|
||
"parameters": [
|
||
{
|
||
"description": "便签内容",
|
||
"name": "note",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/note.Request"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"201": {
|
||
"description": "Created",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.Note"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/notes/{id}": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "按 id 查询单个便签。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"notes"
|
||
],
|
||
"summary": "Get a note",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "便签 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.Note"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "全量更新便签的 title 与 content，字段校验规则同创建。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"notes"
|
||
],
|
||
"summary": "Update a note",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "便签 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
},
|
||
{
|
||
"description": "便签内容",
|
||
"name": "note",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/note.Request"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.Note"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效或 id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "按 id 删除便签，成功时返回 204 且无响应体。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"notes"
|
||
],
|
||
"summary": "Delete a note",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "便签 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
}
|
||
],
|
||
"responses": {
|
||
"204": {
|
||
"description": "删除成功"
|
||
},
|
||
"400": {
|
||
"description": "id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user-groups": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "分页查询用户组列表，按 id 升序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"user-groups"
|
||
],
|
||
"summary": "List user groups",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "页码，默认 1",
|
||
"name": "page",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"type": "integer",
|
||
"example": 20,
|
||
"description": "每页数量，默认 20，最大 100",
|
||
"name": "page_size",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/usergroup.ListResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "创建用户组。name 必填且唯一（最长 50 字符），description 可选（最长 255 字符）；id 由服务端分配。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"user-groups"
|
||
],
|
||
"summary": "Create a user group",
|
||
"parameters": [
|
||
{
|
||
"description": "用户组信息",
|
||
"name": "group",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/usergroup.Request"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"201": {
|
||
"description": "Created",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.UserGroup"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "用户组名称已存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user-groups/{id}": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "按 id 查询单个用户组，id 0 为内置 admin 组。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"user-groups"
|
||
],
|
||
"summary": "Get a user group",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "用户组 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.UserGroup"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "更新用户组的 name 与 description，name 必填且唯一。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"user-groups"
|
||
],
|
||
"summary": "Update a user group",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "用户组 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
},
|
||
{
|
||
"description": "用户组信息",
|
||
"name": "group",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/usergroup.Request"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.UserGroup"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效或 id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "用户组名称已存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "按 id 删除用户组，成功时返回 204 且无响应体。系统内置组或组内仍有用户时返回 409。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"user-groups"
|
||
],
|
||
"summary": "Delete a user group",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 2,
|
||
"description": "用户组 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
}
|
||
],
|
||
"responses": {
|
||
"204": {
|
||
"description": "删除成功"
|
||
},
|
||
"400": {
|
||
"description": "id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "系统内置组不可删除或用户组内仍有用户",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "分页查询用户列表（含所属用户组），按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"users"
|
||
],
|
||
"summary": "List users",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "页码，默认 1",
|
||
"name": "page",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"type": "integer",
|
||
"example": 20,
|
||
"description": "每页数量，默认 20，最大 100",
|
||
"name": "page_size",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/user.ListResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "创建用户并关联用户组。username、email 唯一，password 长度 6-72；不传 group_ids 时默认加入普通用户组（id 1）。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"users"
|
||
],
|
||
"summary": "Create a user",
|
||
"parameters": [
|
||
{
|
||
"description": "用户信息",
|
||
"name": "user",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/user.CreateRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"201": {
|
||
"description": "Created",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.User"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效或用户组不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "用户名或邮箱已存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users/{id}": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "按 id 查询用户（含所属用户组）。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"users"
|
||
],
|
||
"summary": "Get a user",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "用户 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.User"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "更新用户信息，仅更新请求中提供的字段。传 group_ids 会整体替换用户组；password 非空时重置密码。",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"users"
|
||
],
|
||
"summary": "Update a user",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "用户 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
},
|
||
{
|
||
"description": "待更新字段",
|
||
"name": "user",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/user.UpdateRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"schema": {
|
||
"$ref": "#/definitions/model.User"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数无效、id 无效或用户组不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"description": "按 id 删除用户及其用户组成员关系，成功时返回 204 且无响应体。",
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"users"
|
||
],
|
||
"summary": "Delete a user",
|
||
"parameters": [
|
||
{
|
||
"type": "integer",
|
||
"example": 1,
|
||
"description": "用户 ID",
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true
|
||
}
|
||
],
|
||
"responses": {
|
||
"204": {
|
||
"description": "删除成功"
|
||
},
|
||
"400": {
|
||
"description": "id 无效",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或登录已过期",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"403": {
|
||
"description": "需要管理员权限或账号已被禁用",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "记录不存在",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Internal Server Error",
|
||
"schema": {
|
||
"$ref": "#/definitions/httpx.ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"definitions": {
|
||
"api.HealthResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string",
|
||
"example": "数据库不可用"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"example": "ok"
|
||
}
|
||
}
|
||
},
|
||
"auth.LoginRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"account",
|
||
"password"
|
||
],
|
||
"properties": {
|
||
"account": {
|
||
"type": "string",
|
||
"example": "alice"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"example": "secret123"
|
||
}
|
||
}
|
||
},
|
||
"auth.LoginResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"expires_at": {
|
||
"type": "string",
|
||
"example": "2026-09-21T10:00:00+08:00"
|
||
},
|
||
"token": {
|
||
"type": "string",
|
||
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
},
|
||
"user": {
|
||
"$ref": "#/definitions/model.User"
|
||
}
|
||
}
|
||
},
|
||
"auth.RegisterRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"email",
|
||
"password",
|
||
"username"
|
||
],
|
||
"properties": {
|
||
"email": {
|
||
"type": "string",
|
||
"maxLength": 255,
|
||
"example": "alice@example.com"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"maxLength": 72,
|
||
"minLength": 6,
|
||
"example": "secret123"
|
||
},
|
||
"username": {
|
||
"type": "string",
|
||
"maxLength": 50,
|
||
"minLength": 3,
|
||
"example": "alice"
|
||
}
|
||
}
|
||
},
|
||
"httpx.ErrorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string",
|
||
"example": "记录不存在"
|
||
}
|
||
}
|
||
},
|
||
"model.Note": {
|
||
"type": "object",
|
||
"properties": {
|
||
"content": {
|
||
"type": "string"
|
||
},
|
||
"created_at": {
|
||
"type": "string"
|
||
},
|
||
"id": {
|
||
"type": "integer"
|
||
},
|
||
"title": {
|
||
"type": "string"
|
||
},
|
||
"updated_at": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"model.User": {
|
||
"type": "object",
|
||
"properties": {
|
||
"avatar": {
|
||
"type": "string"
|
||
},
|
||
"created_at": {
|
||
"type": "string"
|
||
},
|
||
"email": {
|
||
"type": "string"
|
||
},
|
||
"groups": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/definitions/model.UserGroup"
|
||
}
|
||
},
|
||
"id": {
|
||
"type": "integer"
|
||
},
|
||
"nickname": {
|
||
"type": "string"
|
||
},
|
||
"status": {
|
||
"type": "integer"
|
||
},
|
||
"updated_at": {
|
||
"type": "string"
|
||
},
|
||
"username": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"model.UserGroup": {
|
||
"type": "object",
|
||
"properties": {
|
||
"created_at": {
|
||
"type": "string"
|
||
},
|
||
"description": {
|
||
"type": "string"
|
||
},
|
||
"id": {
|
||
"type": "integer"
|
||
},
|
||
"is_system": {
|
||
"type": "boolean"
|
||
},
|
||
"name": {
|
||
"type": "string"
|
||
},
|
||
"updated_at": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"note.ListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/definitions/model.Note"
|
||
}
|
||
},
|
||
"page": {
|
||
"type": "integer",
|
||
"example": 1
|
||
},
|
||
"page_size": {
|
||
"type": "integer",
|
||
"example": 20
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"example": 42
|
||
}
|
||
}
|
||
},
|
||
"note.Request": {
|
||
"type": "object",
|
||
"required": [
|
||
"title"
|
||
],
|
||
"properties": {
|
||
"content": {
|
||
"type": "string",
|
||
"example": "牛奶、鸡蛋"
|
||
},
|
||
"title": {
|
||
"type": "string",
|
||
"maxLength": 200,
|
||
"example": "购物清单"
|
||
}
|
||
}
|
||
},
|
||
"user.CreateRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"email",
|
||
"password",
|
||
"username"
|
||
],
|
||
"properties": {
|
||
"avatar": {
|
||
"type": "string",
|
||
"maxLength": 255,
|
||
"example": "https://example.com/avatar.png"
|
||
},
|
||
"email": {
|
||
"type": "string",
|
||
"maxLength": 255,
|
||
"example": "alice@example.com"
|
||
},
|
||
"group_ids": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "integer"
|
||
},
|
||
"example": [
|
||
1
|
||
]
|
||
},
|
||
"nickname": {
|
||
"type": "string",
|
||
"maxLength": 50,
|
||
"example": "Alice"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"maxLength": 72,
|
||
"minLength": 6,
|
||
"example": "secret123"
|
||
},
|
||
"status": {
|
||
"type": "integer",
|
||
"enum": [
|
||
0,
|
||
1
|
||
],
|
||
"example": 1
|
||
},
|
||
"username": {
|
||
"type": "string",
|
||
"maxLength": 50,
|
||
"example": "alice"
|
||
}
|
||
}
|
||
},
|
||
"user.ListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/definitions/model.User"
|
||
}
|
||
},
|
||
"page": {
|
||
"type": "integer",
|
||
"example": 1
|
||
},
|
||
"page_size": {
|
||
"type": "integer",
|
||
"example": 20
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"example": 42
|
||
}
|
||
}
|
||
},
|
||
"user.UpdateRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"avatar": {
|
||
"type": "string",
|
||
"maxLength": 255,
|
||
"example": "https://example.com/avatar.png"
|
||
},
|
||
"group_ids": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "integer"
|
||
},
|
||
"example": [
|
||
1
|
||
]
|
||
},
|
||
"nickname": {
|
||
"type": "string",
|
||
"maxLength": 50,
|
||
"example": "Alice"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"maxLength": 72,
|
||
"minLength": 6,
|
||
"example": "secret123"
|
||
},
|
||
"status": {
|
||
"type": "integer",
|
||
"enum": [
|
||
0,
|
||
1
|
||
],
|
||
"example": 1
|
||
}
|
||
}
|
||
},
|
||
"usergroup.ListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/definitions/model.UserGroup"
|
||
}
|
||
},
|
||
"page": {
|
||
"type": "integer",
|
||
"example": 1
|
||
},
|
||
"page_size": {
|
||
"type": "integer",
|
||
"example": 20
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"example": 42
|
||
}
|
||
}
|
||
},
|
||
"usergroup.Request": {
|
||
"type": "object",
|
||
"required": [
|
||
"name"
|
||
],
|
||
"properties": {
|
||
"description": {
|
||
"type": "string",
|
||
"maxLength": 255,
|
||
"example": "负责日常运营"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"maxLength": 50,
|
||
"example": "运营组"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"securityDefinitions": {
|
||
"BearerAuth": {
|
||
"description": "Bearer JWT，格式：Bearer {token}，通过 /auth/login 获取",
|
||
"type": "apiKey",
|
||
"name": "Authorization",
|
||
"in": "header"
|
||
}
|
||
}
|
||
}`
|
||
|
||
// SwaggerInfo holds exported Swagger Info so clients can modify it
|
||
var SwaggerInfo = &swag.Spec{
|
||
Version: "1.0",
|
||
Host: "",
|
||
BasePath: "/api",
|
||
Schemes: []string{},
|
||
Title: "Rill API",
|
||
Description: "Rill 服务端 HTTP API 文档，所有接口以配置项 api.prefix（默认 /api）为前缀，请求与响应均为 JSON。\nSwagger 页面：{prefix}/swagger/index.html；OpenAPI JSON：{prefix}/swagger/doc.json。\n除 health、swagger、auth 外，其余接口需要 Bearer JWT：先调用 /auth/login 获取 token，再在请求头携带 Authorization: Bearer {token}。",
|
||
InfoInstanceName: "swagger",
|
||
SwaggerTemplate: docTemplate,
|
||
LeftDelim: "{{",
|
||
RightDelim: "}}",
|
||
}
|
||
|
||
func init() {
|
||
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
|
||
}
|