kevin/rill
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

接口响应与文档文案全部改为英文

Browse Source 
- 错误响应、健康检查等运行时文案改为英文
- 种子数据英文化，新增迁移 v5 更新存量内置数据（不覆盖手工修改）
- Swagger 注释与 docs/ 文档全英文化
- 补充英文文案断言与 v5 迁移测试
This commit is contained in:
kevin
2026-09-20 02:13:17 +08:00
parent b683fb293e
commit 2858d3c0f7
16 files changed
+603 -489
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/docs.go
+112 -112
View File
@@ -17,7 +17,7 @@ const docTemplate = `{
"paths": {
"/auth/login": {
"post": {
"description": "使用用户名或邮箱登录，成功返回 JWT（有效期见 auth.token_ttl）与用户信息。",
"description": "Login with username or email; returns a JWT (TTL from auth.token_ttl) and the user.",
"consumes": [
"application/json"
],
@@ -30,7 +30,7 @@ const docTemplate = `{
"summary": "Login",
"parameters": [
{
"description": "登录凭证",
"description": "Login credentials",
"name": "credentials",
"in": "body",
"required": true,
@@ -47,19 +47,19 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "账号或密码错误",
"description": "incorrect account or password",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -75,7 +75,7 @@ const docTemplate = `{
},
"/auth/register": {
"post": {
"description": "公开注册，创建普通用户并默认加入普通用户组（id 1）。username 长度 3-50 且唯一，email 唯一，password 长度 6-72。",
"description": "Public registration. Creates a regular user in the default user group (id 1). username is 3-50 chars and unique; email is unique; password is 6-72 chars.",
"consumes": [
"application/json"
],
@@ -88,7 +88,7 @@ const docTemplate = `{
"summary": "Register",
"parameters": [
{
"description": "注册信息",
"description": "Registration payload",
"name": "user",
"in": "body",
"required": true,
@@ -105,13 +105,13 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户名或邮箱已存在",
"description": "username or email already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -127,7 +127,7 @@ const docTemplate = `{
},
"/health": {
"get": {
"description": "检查服务与数据库连接状态；数据库不可用时返回 503。",
"description": "Check service and database connectivity; returns 503 when the database is unavailable.",
"produces": [
"application/json"
],
@@ -158,7 +158,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "分页查询便签列表，按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
"description": "List notes ordered by id DESC. page starts at 1; page_size is 1-100, default 20.",
"produces": [
"application/json"
],
@@ -170,14 +170,14 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "页码，默认 1",
"description": "Page number, default 1",
"name": "page",
"in": "query"
},
{
"type": "integer",
"example": 20,
"description": "每页数量，默认 20，最大 100",
"description": "Page size, default 20, max 100",
"name": "page_size",
"in": "query"
}
@@ -190,13 +190,13 @@ const docTemplate = `{
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -215,7 +215,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "创建便签。title 必填且最长 200 字符，content 可选。",
"description": "Create a note. title is required (max 200 chars); content is optional.",
"consumes": [
"application/json"
],
@@ -228,7 +228,7 @@ const docTemplate = `{
"summary": "Create a note",
"parameters": [
{
"description": "便签内容",
"description": "Note payload",
"name": "note",
"in": "body",
"required": true,
@@ -245,19 +245,19 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -278,7 +278,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "按 id 查询单个便签。",
"description": "Get a note by id.",
"produces": [
"application/json"
],
@@ -290,7 +290,7 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "便签 ID",
"description": "Note ID",
"name": "id",
"in": "path",
"required": true
@@ -304,25 +304,25 @@ const docTemplate = `{
}
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -341,7 +341,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "全量更新便签的 title 与 content，字段校验规则同创建。",
"description": "Update title and content; validation is the same as create.",
"consumes": [
"application/json"
],
@@ -356,13 +356,13 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "便签 ID",
"description": "Note ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "便签内容",
"description": "Note payload",
"name": "note",
"in": "body",
"required": true,
@@ -379,25 +379,25 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效或 id 无效",
"description": "invalid request or id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -416,7 +416,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "按 id 删除便签，成功时返回 204 且无响应体。",
"description": "Delete a note by id; returns 204 with no body on success.",
"produces": [
"application/json"
],
@@ -428,7 +428,7 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "便签 ID",
"description": "Note ID",
"name": "id",
"in": "path",
"required": true
@@ -436,28 +436,28 @@ const docTemplate = `{
],
"responses": {
"204": {
"description": "删除成功"
"description": "Deleted"
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -478,7 +478,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "分页查询用户组列表，按 id 升序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
"description": "List user groups ordered by id ASC. page starts at 1; page_size is 1-100, default 20.",
"produces": [
"application/json"
],
@@ -490,14 +490,14 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "页码，默认 1",
"description": "Page number, default 1",
"name": "page",
"in": "query"
},
{
"type": "integer",
"example": 20,
"description": "每页数量，默认 20，最大 100",
"description": "Page size, default 20, max 100",
"name": "page_size",
"in": "query"
}
@@ -510,13 +510,13 @@ const docTemplate = `{
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -535,7 +535,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "创建用户组。name 必填且唯一（最长 50 字符），description 可选（最长 255 字符）；id 由服务端分配。",
"description": "Create a user group. name is required and unique (max 50 chars); description is optional (max 255 chars); id is assigned by the server.",
"consumes": [
"application/json"
],
@@ -548,7 +548,7 @@ const docTemplate = `{
"summary": "Create a user group",
"parameters": [
{
"description": "用户组信息",
"description": "User group payload",
"name": "group",
"in": "body",
"required": true,
@@ -565,25 +565,25 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户组名称已存在",
"description": "user group name already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -604,7 +604,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "按 id 查询单个用户组，id 0 为内置 admin 组。",
"description": "Get a user group by id; id 0 is the built-in admin group.",
"produces": [
"application/json"
],
@@ -616,7 +616,7 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "用户组 ID",
"description": "User group ID",
"name": "id",
"in": "path",
"required": true
@@ -630,25 +630,25 @@ const docTemplate = `{
}
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -667,7 +667,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "更新用户组的 name 与 description，name 必填且唯一。",
"description": "Update a user group's name and description; name is required and unique.",
"consumes": [
"application/json"
],
@@ -682,13 +682,13 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "用户组 ID",
"description": "User group ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "用户组信息",
"description": "User group payload",
"name": "group",
"in": "body",
"required": true,
@@ -705,31 +705,31 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效或 id 无效",
"description": "invalid request or id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户组名称已存在",
"description": "user group name already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -748,7 +748,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "按 id 删除用户组，成功时返回 204 且无响应体。系统内置组或组内仍有用户时返回 409。",
"description": "Delete a user group by id; returns 204 with no body on success. Returns 409 for system groups or when the group still has members.",
"produces": [
"application/json"
],
@@ -760,7 +760,7 @@ const docTemplate = `{
{
"type": "integer",
"example": 2,
"description": "用户组 ID",
"description": "User group ID",
"name": "id",
"in": "path",
"required": true
@@ -768,34 +768,34 @@ const docTemplate = `{
],
"responses": {
"204": {
"description": "删除成功"
"description": "Deleted"
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "系统内置组不可删除或用户组内仍有用户",
"description": "system group cannot be deleted or group still has members",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -816,7 +816,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "分页查询用户列表（含所属用户组），按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
"description": "List users with their groups, ordered by id DESC. page starts at 1; page_size is 1-100, default 20.",
"produces": [
"application/json"
],
@@ -828,14 +828,14 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "页码，默认 1",
"description": "Page number, default 1",
"name": "page",
"in": "query"
},
{
"type": "integer",
"example": 20,
"description": "每页数量，默认 20，最大 100",
"description": "Page size, default 20, max 100",
"name": "page_size",
"in": "query"
}
@@ -848,13 +848,13 @@ const docTemplate = `{
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -873,7 +873,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "创建用户并关联用户组。username、email 唯一，password 长度 6-72；不传 group_ids 时默认加入普通用户组（id 1）。",
"description": "Create a user and assign groups. username and email are unique; password is 6-72 chars; defaults to the regular user group (id 1) when group_ids is omitted.",
"consumes": [
"application/json"
],
@@ -886,7 +886,7 @@ const docTemplate = `{
"summary": "Create a user",
"parameters": [
{
"description": "用户信息",
"description": "User payload",
"name": "user",
"in": "body",
"required": true,
@@ -903,25 +903,25 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效或用户组不存在",
"description": "invalid request or user group not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户名或邮箱已存在",
"description": "username or email already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -942,7 +942,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "按 id 查询用户（含所属用户组）。",
"description": "Get a user by id, including groups.",
"produces": [
"application/json"
],
@@ -954,7 +954,7 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "用户 ID",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
@@ -968,25 +968,25 @@ const docTemplate = `{
}
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -1005,7 +1005,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "更新用户信息，仅更新请求中提供的字段。传 group_ids 会整体替换用户组；password 非空时重置密码。",
"description": "Update user fields. group_ids replaces all groups; a non-empty password resets the password.",
"consumes": [
"application/json"
],
@@ -1020,13 +1020,13 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "用户 ID",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "待更新字段",
"description": "Fields to update",
"name": "user",
"in": "body",
"required": true,
@@ -1043,25 +1043,25 @@ const docTemplate = `{
}
},
"400": {
"description": "参数无效、id 无效或用户组不存在",
"description": "invalid request, id, or user group not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -1080,7 +1080,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "按 id 删除用户及其用户组成员关系，成功时返回 204 且无响应体。",
"description": "Delete a user and their group memberships; returns 204 with no body on success.",
"produces": [
"application/json"
],
@@ -1092,7 +1092,7 @@ const docTemplate = `{
{
"type": "integer",
"example": 1,
"description": "用户 ID",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
@@ -1100,28 +1100,28 @@ const docTemplate = `{
],
"responses": {
"204": {
"description": "删除成功"
"description": "Deleted"
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -1142,7 +1142,7 @@ const docTemplate = `{
"properties": {
"error": {
"type": "string",
"example": "数据库不可用"
"example": "database unavailable"
},
"status": {
"type": "string",
@@ -1215,7 +1215,7 @@ const docTemplate = `{
"properties": {
"error": {
"type": "string",
"example": "记录不存在"
"example": "record not found"
}
}
},
@@ -1328,12 +1328,12 @@ const docTemplate = `{
"properties": {
"content": {
"type": "string",
"example": "牛奶、鸡蛋"
"example": "Milk, eggs"
},
"title": {
"type": "string",
"maxLength": 200,
"example": "购物清单"
"example": "Shopping list"
}
}
},
@@ -1483,19 +1483,19 @@ const docTemplate = `{
"description": {
"type": "string",
"maxLength": 255,
"example": "负责日常运营"
"example": "Handles daily operations"
},
"name": {
"type": "string",
"maxLength": 50,
"example": "运营组"
"example": "Operations"
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"description": "Bearer JWT，格式：Bearer {token}，通过 /auth/login 获取",
"description": "Bearer JWT, format: Bearer {token}, obtained from /auth/login",
"type": "apiKey",
"name": "Authorization",
"in": "header"
@@ -1510,7 +1510,7 @@ var SwaggerInfo = &swag.Spec{
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}。",
Description: "Rill server HTTP API documentation. All endpoints are prefixed with api.prefix (default /api); requests and responses are JSON.\nSwagger UI: {prefix}/swagger/index.html; OpenAPI JSON: {prefix}/swagger/doc.json.\nExcept for health, swagger, and auth, all endpoints require a Bearer JWT: call /auth/login to get a token, then send Authorization: Bearer {token}.",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
docs/swagger.json
+112 -112
View File
@@ -1,7 +1,7 @@
{
"swagger": "2.0",
"info": {
"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}。",
"description": "Rill server HTTP API documentation. All endpoints are prefixed with api.prefix (default /api); requests and responses are JSON.\nSwagger UI: {prefix}/swagger/index.html; OpenAPI JSON: {prefix}/swagger/doc.json.\nExcept for health, swagger, and auth, all endpoints require a Bearer JWT: call /auth/login to get a token, then send Authorization: Bearer {token}.",
"title": "Rill API",
"contact": {},
"version": "1.0"
@@ -10,7 +10,7 @@
"paths": {
"/auth/login": {
"post": {
"description": "使用用户名或邮箱登录，成功返回 JWT（有效期见 auth.token_ttl）与用户信息。",
"description": "Login with username or email; returns a JWT (TTL from auth.token_ttl) and the user.",
"consumes": [
"application/json"
],
@@ -23,7 +23,7 @@
"summary": "Login",
"parameters": [
{
"description": "登录凭证",
"description": "Login credentials",
"name": "credentials",
"in": "body",
"required": true,
@@ -40,19 +40,19 @@
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "账号或密码错误",
"description": "incorrect account or password",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -68,7 +68,7 @@
},
"/auth/register": {
"post": {
"description": "公开注册，创建普通用户并默认加入普通用户组（id 1）。username 长度 3-50 且唯一，email 唯一，password 长度 6-72。",
"description": "Public registration. Creates a regular user in the default user group (id 1). username is 3-50 chars and unique; email is unique; password is 6-72 chars.",
"consumes": [
"application/json"
],
@@ -81,7 +81,7 @@
"summary": "Register",
"parameters": [
{
"description": "注册信息",
"description": "Registration payload",
"name": "user",
"in": "body",
"required": true,
@@ -98,13 +98,13 @@
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户名或邮箱已存在",
"description": "username or email already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -120,7 +120,7 @@
},
"/health": {
"get": {
"description": "检查服务与数据库连接状态；数据库不可用时返回 503。",
"description": "Check service and database connectivity; returns 503 when the database is unavailable.",
"produces": [
"application/json"
],
@@ -151,7 +151,7 @@
"BearerAuth": []
}
],
"description": "分页查询便签列表，按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
"description": "List notes ordered by id DESC. page starts at 1; page_size is 1-100, default 20.",
"produces": [
"application/json"
],
@@ -163,14 +163,14 @@
{
"type": "integer",
"example": 1,
"description": "页码，默认 1",
"description": "Page number, default 1",
"name": "page",
"in": "query"
},
{
"type": "integer",
"example": 20,
"description": "每页数量，默认 20，最大 100",
"description": "Page size, default 20, max 100",
"name": "page_size",
"in": "query"
}
@@ -183,13 +183,13 @@
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -208,7 +208,7 @@
"BearerAuth": []
}
],
"description": "创建便签。title 必填且最长 200 字符，content 可选。",
"description": "Create a note. title is required (max 200 chars); content is optional.",
"consumes": [
"application/json"
],
@@ -221,7 +221,7 @@
"summary": "Create a note",
"parameters": [
{
"description": "便签内容",
"description": "Note payload",
"name": "note",
"in": "body",
"required": true,
@@ -238,19 +238,19 @@
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -271,7 +271,7 @@
"BearerAuth": []
}
],
"description": "按 id 查询单个便签。",
"description": "Get a note by id.",
"produces": [
"application/json"
],
@@ -283,7 +283,7 @@
{
"type": "integer",
"example": 1,
"description": "便签 ID",
"description": "Note ID",
"name": "id",
"in": "path",
"required": true
@@ -297,25 +297,25 @@
}
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -334,7 +334,7 @@
"BearerAuth": []
}
],
"description": "全量更新便签的 title 与 content，字段校验规则同创建。",
"description": "Update title and content; validation is the same as create.",
"consumes": [
"application/json"
],
@@ -349,13 +349,13 @@
{
"type": "integer",
"example": 1,
"description": "便签 ID",
"description": "Note ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "便签内容",
"description": "Note payload",
"name": "note",
"in": "body",
"required": true,
@@ -372,25 +372,25 @@
}
},
"400": {
"description": "参数无效或 id 无效",
"description": "invalid request or id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -409,7 +409,7 @@
"BearerAuth": []
}
],
"description": "按 id 删除便签，成功时返回 204 且无响应体。",
"description": "Delete a note by id; returns 204 with no body on success.",
"produces": [
"application/json"
],
@@ -421,7 +421,7 @@
{
"type": "integer",
"example": 1,
"description": "便签 ID",
"description": "Note ID",
"name": "id",
"in": "path",
"required": true
@@ -429,28 +429,28 @@
],
"responses": {
"204": {
"description": "删除成功"
"description": "Deleted"
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "账号已被禁用",
"description": "account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -471,7 +471,7 @@
"BearerAuth": []
}
],
"description": "分页查询用户组列表，按 id 升序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
"description": "List user groups ordered by id ASC. page starts at 1; page_size is 1-100, default 20.",
"produces": [
"application/json"
],
@@ -483,14 +483,14 @@
{
"type": "integer",
"example": 1,
"description": "页码，默认 1",
"description": "Page number, default 1",
"name": "page",
"in": "query"
},
{
"type": "integer",
"example": 20,
"description": "每页数量，默认 20，最大 100",
"description": "Page size, default 20, max 100",
"name": "page_size",
"in": "query"
}
@@ -503,13 +503,13 @@
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -528,7 +528,7 @@
"BearerAuth": []
}
],
"description": "创建用户组。name 必填且唯一（最长 50 字符），description 可选（最长 255 字符）；id 由服务端分配。",
"description": "Create a user group. name is required and unique (max 50 chars); description is optional (max 255 chars); id is assigned by the server.",
"consumes": [
"application/json"
],
@@ -541,7 +541,7 @@
"summary": "Create a user group",
"parameters": [
{
"description": "用户组信息",
"description": "User group payload",
"name": "group",
"in": "body",
"required": true,
@@ -558,25 +558,25 @@
}
},
"400": {
"description": "参数无效",
"description": "invalid request",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户组名称已存在",
"description": "user group name already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -597,7 +597,7 @@
"BearerAuth": []
}
],
"description": "按 id 查询单个用户组，id 0 为内置 admin 组。",
"description": "Get a user group by id; id 0 is the built-in admin group.",
"produces": [
"application/json"
],
@@ -609,7 +609,7 @@
{
"type": "integer",
"example": 1,
"description": "用户组 ID",
"description": "User group ID",
"name": "id",
"in": "path",
"required": true
@@ -623,25 +623,25 @@
}
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -660,7 +660,7 @@
"BearerAuth": []
}
],
"description": "更新用户组的 name 与 description，name 必填且唯一。",
"description": "Update a user group's name and description; name is required and unique.",
"consumes": [
"application/json"
],
@@ -675,13 +675,13 @@
{
"type": "integer",
"example": 1,
"description": "用户组 ID",
"description": "User group ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "用户组信息",
"description": "User group payload",
"name": "group",
"in": "body",
"required": true,
@@ -698,31 +698,31 @@
}
},
"400": {
"description": "参数无效或 id 无效",
"description": "invalid request or id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户组名称已存在",
"description": "user group name already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -741,7 +741,7 @@
"BearerAuth": []
}
],
"description": "按 id 删除用户组，成功时返回 204 且无响应体。系统内置组或组内仍有用户时返回 409。",
"description": "Delete a user group by id; returns 204 with no body on success. Returns 409 for system groups or when the group still has members.",
"produces": [
"application/json"
],
@@ -753,7 +753,7 @@
{
"type": "integer",
"example": 2,
"description": "用户组 ID",
"description": "User group ID",
"name": "id",
"in": "path",
"required": true
@@ -761,34 +761,34 @@
],
"responses": {
"204": {
"description": "删除成功"
"description": "Deleted"
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "系统内置组不可删除或用户组内仍有用户",
"description": "system group cannot be deleted or group still has members",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -809,7 +809,7 @@
"BearerAuth": []
}
],
"description": "分页查询用户列表（含所属用户组），按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。",
"description": "List users with their groups, ordered by id DESC. page starts at 1; page_size is 1-100, default 20.",
"produces": [
"application/json"
],
@@ -821,14 +821,14 @@
{
"type": "integer",
"example": 1,
"description": "页码，默认 1",
"description": "Page number, default 1",
"name": "page",
"in": "query"
},
{
"type": "integer",
"example": 20,
"description": "每页数量，默认 20，最大 100",
"description": "Page size, default 20, max 100",
"name": "page_size",
"in": "query"
}
@@ -841,13 +841,13 @@
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -866,7 +866,7 @@
"BearerAuth": []
}
],
"description": "创建用户并关联用户组。username、email 唯一，password 长度 6-72；不传 group_ids 时默认加入普通用户组（id 1）。",
"description": "Create a user and assign groups. username and email are unique; password is 6-72 chars; defaults to the regular user group (id 1) when group_ids is omitted.",
"consumes": [
"application/json"
],
@@ -879,7 +879,7 @@
"summary": "Create a user",
"parameters": [
{
"description": "用户信息",
"description": "User payload",
"name": "user",
"in": "body",
"required": true,
@@ -896,25 +896,25 @@
}
},
"400": {
"description": "参数无效或用户组不存在",
"description": "invalid request or user group not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"409": {
"description": "用户名或邮箱已存在",
"description": "username or email already exists",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -935,7 +935,7 @@
"BearerAuth": []
}
],
"description": "按 id 查询用户（含所属用户组）。",
"description": "Get a user by id, including groups.",
"produces": [
"application/json"
],
@@ -947,7 +947,7 @@
{
"type": "integer",
"example": 1,
"description": "用户 ID",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
@@ -961,25 +961,25 @@
}
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -998,7 +998,7 @@
"BearerAuth": []
}
],
"description": "更新用户信息，仅更新请求中提供的字段。传 group_ids 会整体替换用户组；password 非空时重置密码。",
"description": "Update user fields. group_ids replaces all groups; a non-empty password resets the password.",
"consumes": [
"application/json"
],
@@ -1013,13 +1013,13 @@
{
"type": "integer",
"example": 1,
"description": "用户 ID",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "待更新字段",
"description": "Fields to update",
"name": "user",
"in": "body",
"required": true,
@@ -1036,25 +1036,25 @@
}
},
"400": {
"description": "参数无效、id 无效或用户组不存在",
"description": "invalid request, id, or user group not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -1073,7 +1073,7 @@
"BearerAuth": []
}
],
"description": "按 id 删除用户及其用户组成员关系，成功时返回 204 且无响应体。",
"description": "Delete a user and their group memberships; returns 204 with no body on success.",
"produces": [
"application/json"
],
@@ -1085,7 +1085,7 @@
{
"type": "integer",
"example": 1,
"description": "用户 ID",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
@@ -1093,28 +1093,28 @@
],
"responses": {
"204": {
"description": "删除成功"
"description": "Deleted"
},
"400": {
"description": "id 无效",
"description": "invalid id",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"401": {
"description": "未登录或登录已过期",
"description": "unauthorized or session expired",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"403": {
"description": "需要管理员权限或账号已被禁用",
"description": "admin permission required or account disabled",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
},
"404": {
"description": "记录不存在",
"description": "record not found",
"schema": {
"$ref": "#/definitions/httpx.ErrorResponse"
}
@@ -1135,7 +1135,7 @@
"properties": {
"error": {
"type": "string",
"example": "数据库不可用"
"example": "database unavailable"
},
"status": {
"type": "string",
@@ -1208,7 +1208,7 @@
"properties": {
"error": {
"type": "string",
"example": "记录不存在"
"example": "record not found"
}
}
},
@@ -1321,12 +1321,12 @@
"properties": {
"content": {
"type": "string",
"example": "牛奶、鸡蛋"
"example": "Milk, eggs"
},
"title": {
"type": "string",
"maxLength": 200,
"example": "购物清单"
"example": "Shopping list"
}
}
},
@@ -1476,19 +1476,19 @@
"description": {
"type": "string",
"maxLength": 255,
"example": "负责日常运营"
"example": "Handles daily operations"
},
"name": {
"type": "string",
"maxLength": 50,
"example": "运营组"
"example": "Operations"
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"description": "Bearer JWT，格式：Bearer {token}，通过 /auth/login 获取",
"description": "Bearer JWT, format: Bearer {token}, obtained from /auth/login",
"type": "apiKey",
"name": "Authorization",
"in": "header"
docs/swagger.yaml
+128 -116
View File
@@ -3,7 +3,7 @@ definitions:
api.HealthResponse:
properties:
error:
example: 数据库不可用
example: database unavailable
type: string
status:
example: ok
@@ -56,7 +56,7 @@ definitions:
httpx.ErrorResponse:
properties:
error:
example: 记录不存在
example: record not found
type: string
type: object
model.Note:
@@ -129,10 +129,10 @@ definitions:
note.Request:
properties:
content:
example: 牛奶、鸡蛋
example: Milk, eggs
type: string
title:
example: 购物清单
example: Shopping list
maxLength: 200
type: string
required:
@@ -241,11 +241,11 @@ definitions:
usergroup.Request:
properties:
description:
example: 负责日常运营
example: Handles daily operations
maxLength: 255
type: string
name:
example: 运营组
example: Operations
maxLength: 50
type: string
required:
@@ -254,9 +254,9 @@ definitions:
info:
contact: {}
description: |-
Rill 服务端 HTTP API 文档，所有接口以配置项 api.prefix（默认 /api）为前缀，请求与响应均为 JSON。
Swagger 页面：{prefix}/swagger/index.html；OpenAPI JSON：{prefix}/swagger/doc.json。
除 health、swagger、auth 外，其余接口需要 Bearer JWT：先调用 /auth/login 获取 token，再在请求头携带 Authorization: Bearer {token}。
Rill server HTTP API documentation. All endpoints are prefixed with api.prefix (default /api); requests and responses are JSON.
Swagger UI: {prefix}/swagger/index.html; OpenAPI JSON: {prefix}/swagger/doc.json.
Except for health, swagger, and auth, all endpoints require a Bearer JWT: call /auth/login to get a token, then send Authorization: Bearer {token}.
title: Rill API
version: "1.0"
paths:
@@ -264,9 +264,10 @@ paths:
post:
consumes:
- application/json
description: 使用用户名或邮箱登录，成功返回 JWT（有效期见 auth.token_ttl）与用户信息。
description: Login with username or email; returns a JWT (TTL from auth.token_ttl)
and the user.
parameters:
- description: 登录凭证
- description: Login credentials
in: body
name: credentials
required: true
@@ -280,15 +281,15 @@ paths:
schema:
$ref: '#/definitions/auth.LoginResponse'
"400":
description: 参数无效
description: invalid request
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 账号或密码错误
description: incorrect account or password
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 账号已被禁用
description: account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -302,10 +303,11 @@ paths:
post:
consumes:
- application/json
description: 公开注册，创建普通用户并默认加入普通用户组（id 1）。username 长度 3-50 且唯一，email 唯一，password
长度 6-72。
description: Public registration. Creates a regular user in the default user
group (id 1). username is 3-50 chars and unique; email is unique; password
is 6-72 chars.
parameters:
- description: 注册信息
- description: Registration payload
in: body
name: user
required: true
@@ -319,11 +321,11 @@ paths:
schema:
$ref: '#/definitions/model.User'
"400":
description: 参数无效
description: invalid request
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"409":
description: 用户名或邮箱已存在
description: username or email already exists
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -335,7 +337,8 @@ paths:
- auth
/health:
get:
description: 检查服务与数据库连接状态；数据库不可用时返回 503。
description: Check service and database connectivity; returns 503 when the database
is unavailable.
produces:
- application/json
responses:
@@ -352,14 +355,15 @@ paths:
- system
/notes:
get:
description: 分页查询便签列表，按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。
description: List notes ordered by id DESC. page starts at 1; page_size is 1-100,
default 20.
parameters:
- description: 页码，默认 1
- description: Page number, default 1
example: 1
in: query
name: page
type: integer
- description: 每页数量，默认 20，最大 100
- description: Page size, default 20, max 100
example: 20
in: query
name: page_size
@@ -372,11 +376,11 @@ paths:
schema:
$ref: '#/definitions/note.ListResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 账号已被禁用
description: account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -391,9 +395,9 @@ paths:
post:
consumes:
- application/json
description: 创建便签。title 必填且最长 200 字符，content 可选。
description: Create a note. title is required (max 200 chars); content is optional.
parameters:
- description: 便签内容
- description: Note payload
in: body
name: note
required: true
@@ -407,15 +411,15 @@ paths:
schema:
$ref: '#/definitions/model.Note'
"400":
description: 参数无效
description: invalid request
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 账号已被禁用
description: account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -429,9 +433,9 @@ paths:
- notes
/notes/{id}:
delete:
description: 按 id 删除便签，成功时返回 204 且无响应体。
description: Delete a note by id; returns 204 with no body on success.
parameters:
- description: 便签 ID
- description: Note ID
example: 1
in: path
name: id
@@ -441,21 +445,21 @@ paths:
- application/json
responses:
"204":
description: 删除成功
description: Deleted
"400":
description: id 无效
description: invalid id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 账号已被禁用
description: account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -468,9 +472,9 @@ paths:
tags:
- notes
get:
description: 按 id 查询单个便签。
description: Get a note by id.
parameters:
- description: 便签 ID
- description: Note ID
example: 1
in: path
name: id
@@ -484,19 +488,19 @@ paths:
schema:
$ref: '#/definitions/model.Note'
"400":
description: id 无效
description: invalid id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 账号已被禁用
description: account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -511,15 +515,15 @@ paths:
put:
consumes:
- application/json
description: 全量更新便签的 title 与 content，字段校验规则同创建。
description: Update title and content; validation is the same as create.
parameters:
- description: 便签 ID
- description: Note ID
example: 1
in: path
name: id
required: true
type: integer
- description: 便签内容
- description: Note payload
in: body
name: note
required: true
@@ -533,19 +537,19 @@ paths:
schema:
$ref: '#/definitions/model.Note'
"400":
description: 参数无效或 id 无效
description: invalid request or id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 账号已被禁用
description: account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -559,14 +563,15 @@ paths:
- notes
/user-groups:
get:
description: 分页查询用户组列表，按 id 升序返回。page 从 1 开始；page_size 取值 1-100，默认 20。
description: List user groups ordered by id ASC. page starts at 1; page_size
is 1-100, default 20.
parameters:
- description: 页码，默认 1
- description: Page number, default 1
example: 1
in: query
name: page
type: integer
- description: 每页数量，默认 20，最大 100
- description: Page size, default 20, max 100
example: 20
in: query
name: page_size
@@ -579,11 +584,11 @@ paths:
schema:
$ref: '#/definitions/usergroup.ListResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -598,9 +603,10 @@ paths:
post:
consumes:
- application/json
description: 创建用户组。name 必填且唯一（最长 50 字符），description 可选（最长 255 字符）；id 由服务端分配。
description: Create a user group. name is required and unique (max 50 chars);
description is optional (max 255 chars); id is assigned by the server.
parameters:
- description: 用户组信息
- description: User group payload
in: body
name: group
required: true
@@ -614,19 +620,19 @@ paths:
schema:
$ref: '#/definitions/model.UserGroup'
"400":
description: 参数无效
description: invalid request
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"409":
description: 用户组名称已存在
description: user group name already exists
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -640,9 +646,10 @@ paths:
- user-groups
/user-groups/{id}:
delete:
description: 按 id 删除用户组，成功时返回 204 且无响应体。系统内置组或组内仍有用户时返回 409。
description: Delete a user group by id; returns 204 with no body on success.
Returns 409 for system groups or when the group still has members.
parameters:
- description: 用户组 ID
- description: User group ID
example: 2
in: path
name: id
@@ -652,25 +659,25 @@ paths:
- application/json
responses:
"204":
description: 删除成功
description: Deleted
"400":
description: id 无效
description: invalid id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"409":
description: 系统内置组不可删除或用户组内仍有用户
description: system group cannot be deleted or group still has members
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -683,9 +690,9 @@ paths:
tags:
- user-groups
get:
description: 按 id 查询单个用户组，id 0 为内置 admin 组。
description: Get a user group by id; id 0 is the built-in admin group.
parameters:
- description: 用户组 ID
- description: User group ID
example: 1
in: path
name: id
@@ -699,19 +706,19 @@ paths:
schema:
$ref: '#/definitions/model.UserGroup'
"400":
description: id 无效
description: invalid id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -726,15 +733,16 @@ paths:
put:
consumes:
- application/json
description: 更新用户组的 name 与 description，name 必填且唯一。
description: Update a user group's name and description; name is required and
unique.
parameters:
- description: 用户组 ID
- description: User group ID
example: 1
in: path
name: id
required: true
type: integer
- description: 用户组信息
- description: User group payload
in: body
name: group
required: true
@@ -748,23 +756,23 @@ paths:
schema:
$ref: '#/definitions/model.UserGroup'
"400":
description: 参数无效或 id 无效
description: invalid request or id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"409":
description: 用户组名称已存在
description: user group name already exists
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -778,14 +786,15 @@ paths:
- user-groups
/users:
get:
description: 分页查询用户列表（含所属用户组），按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。
description: List users with their groups, ordered by id DESC. page starts at
1; page_size is 1-100, default 20.
parameters:
- description: 页码，默认 1
- description: Page number, default 1
example: 1
in: query
name: page
type: integer
- description: 每页数量，默认 20，最大 100
- description: Page size, default 20, max 100
example: 20
in: query
name: page_size
@@ -798,11 +807,11 @@ paths:
schema:
$ref: '#/definitions/user.ListResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -817,10 +826,11 @@ paths:
post:
consumes:
- application/json
description: 创建用户并关联用户组。username、email 唯一，password 长度 6-72；不传 group_ids 时默认加入普通用户组（id
1）。
description: Create a user and assign groups. username and email are unique;
password is 6-72 chars; defaults to the regular user group (id 1) when group_ids
is omitted.
parameters:
- description: 用户信息
- description: User payload
in: body
name: user
required: true
@@ -834,19 +844,19 @@ paths:
schema:
$ref: '#/definitions/model.User'
"400":
description: 参数无效或用户组不存在
description: invalid request or user group not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"409":
description: 用户名或邮箱已存在
description: username or email already exists
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -860,9 +870,10 @@ paths:
- users
/users/{id}:
delete:
description: 按 id 删除用户及其用户组成员关系，成功时返回 204 且无响应体。
description: Delete a user and their group memberships; returns 204 with no
body on success.
parameters:
- description: 用户 ID
- description: User ID
example: 1
in: path
name: id
@@ -872,21 +883,21 @@ paths:
- application/json
responses:
"204":
description: 删除成功
description: Deleted
"400":
description: id 无效
description: invalid id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -899,9 +910,9 @@ paths:
tags:
- users
get:
description: 按 id 查询用户（含所属用户组）。
description: Get a user by id, including groups.
parameters:
- description: 用户 ID
- description: User ID
example: 1
in: path
name: id
@@ -915,19 +926,19 @@ paths:
schema:
$ref: '#/definitions/model.User'
"400":
description: id 无效
description: invalid id
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -942,15 +953,16 @@ paths:
put:
consumes:
- application/json
description: 更新用户信息，仅更新请求中提供的字段。传 group_ids 会整体替换用户组；password 非空时重置密码。
description: Update user fields. group_ids replaces all groups; a non-empty
password resets the password.
parameters:
- description: 用户 ID
- description: User ID
example: 1
in: path
name: id
required: true
type: integer
- description: 待更新字段
- description: Fields to update
in: body
name: user
required: true
@@ -964,19 +976,19 @@ paths:
schema:
$ref: '#/definitions/model.User'
"400":
description: 参数无效、id 无效或用户组不存在
description: invalid request, id, or user group not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"401":
description: 未登录或登录已过期
description: unauthorized or session expired
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"403":
description: 需要管理员权限或账号已被禁用
description: admin permission required or account disabled
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"404":
description: 记录不存在
description: record not found
schema:
$ref: '#/definitions/httpx.ErrorResponse'
"500":
@@ -990,7 +1002,7 @@ paths:
- users
securityDefinitions:
BearerAuth:
description: Bearer JWT，格式：Bearer {token}，通过 /auth/login 获取
description: 'Bearer JWT, format: Bearer {token}, obtained from /auth/login'
in: header
name: Authorization
type: apiKey