增加 Swagger API 文档页面
This commit is contained in:
10 files changed
+3284
-62
No files matched your search
+1089
File diff suppressed because it is too large.
Load diff
+1064
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,723 @@
|
||||
basePath: /api
|
||||
definitions:
|
||||
api.ErrorResponse:
|
||||
properties:
|
||||
error:
|
||||
example: 记录不存在
|
||||
type: string
|
||||
type: object
|
||||
api.HealthResponse:
|
||||
properties:
|
||||
error:
|
||||
example: 数据库不可用
|
||||
type: string
|
||||
status:
|
||||
example: ok
|
||||
type: string
|
||||
type: object
|
||||
api.NoteListResponse:
|
||||
properties:
|
||||
items:
|
||||
items:
|
||||
$ref: '#/definitions/model.Note'
|
||||
type: array
|
||||
page:
|
||||
example: 1
|
||||
type: integer
|
||||
page_size:
|
||||
example: 20
|
||||
type: integer
|
||||
total:
|
||||
example: 42
|
||||
type: integer
|
||||
type: object
|
||||
api.NoteRequest:
|
||||
properties:
|
||||
content:
|
||||
example: 牛奶、鸡蛋
|
||||
type: string
|
||||
title:
|
||||
example: 购物清单
|
||||
maxLength: 200
|
||||
type: string
|
||||
required:
|
||||
- title
|
||||
type: object
|
||||
api.UserCreateRequest:
|
||||
properties:
|
||||
avatar:
|
||||
example: https://example.com/avatar.png
|
||||
maxLength: 255
|
||||
type: string
|
||||
email:
|
||||
example: alice@example.com
|
||||
maxLength: 255
|
||||
type: string
|
||||
group_ids:
|
||||
example:
|
||||
- 1
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
nickname:
|
||||
example: Alice
|
||||
maxLength: 50
|
||||
type: string
|
||||
password:
|
||||
example: secret123
|
||||
maxLength: 72
|
||||
minLength: 6
|
||||
type: string
|
||||
status:
|
||||
enum:
|
||||
- 0
|
||||
- 1
|
||||
example: 1
|
||||
type: integer
|
||||
username:
|
||||
example: alice
|
||||
maxLength: 50
|
||||
type: string
|
||||
required:
|
||||
- email
|
||||
- password
|
||||
- username
|
||||
type: object
|
||||
api.UserGroupListResponse:
|
||||
properties:
|
||||
items:
|
||||
items:
|
||||
$ref: '#/definitions/model.UserGroup'
|
||||
type: array
|
||||
page:
|
||||
example: 1
|
||||
type: integer
|
||||
page_size:
|
||||
example: 20
|
||||
type: integer
|
||||
total:
|
||||
example: 42
|
||||
type: integer
|
||||
type: object
|
||||
api.UserGroupRequest:
|
||||
properties:
|
||||
description:
|
||||
example: 负责日常运营
|
||||
maxLength: 255
|
||||
type: string
|
||||
name:
|
||||
example: 运营组
|
||||
maxLength: 50
|
||||
type: string
|
||||
required:
|
||||
- name
|
||||
type: object
|
||||
api.UserListResponse:
|
||||
properties:
|
||||
items:
|
||||
items:
|
||||
$ref: '#/definitions/model.User'
|
||||
type: array
|
||||
page:
|
||||
example: 1
|
||||
type: integer
|
||||
page_size:
|
||||
example: 20
|
||||
type: integer
|
||||
total:
|
||||
example: 42
|
||||
type: integer
|
||||
type: object
|
||||
api.UserUpdateRequest:
|
||||
properties:
|
||||
avatar:
|
||||
example: https://example.com/avatar.png
|
||||
maxLength: 255
|
||||
type: string
|
||||
group_ids:
|
||||
example:
|
||||
- 1
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
nickname:
|
||||
example: Alice
|
||||
maxLength: 50
|
||||
type: string
|
||||
password:
|
||||
example: secret123
|
||||
maxLength: 72
|
||||
minLength: 6
|
||||
type: string
|
||||
status:
|
||||
enum:
|
||||
- 0
|
||||
- 1
|
||||
example: 1
|
||||
type: integer
|
||||
type: object
|
||||
model.Note:
|
||||
properties:
|
||||
content:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
id:
|
||||
type: integer
|
||||
title:
|
||||
type: string
|
||||
updated_at:
|
||||
type: string
|
||||
type: object
|
||||
model.User:
|
||||
properties:
|
||||
avatar:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
email:
|
||||
type: string
|
||||
groups:
|
||||
items:
|
||||
$ref: '#/definitions/model.UserGroup'
|
||||
type: array
|
||||
id:
|
||||
type: integer
|
||||
nickname:
|
||||
type: string
|
||||
status:
|
||||
type: integer
|
||||
updated_at:
|
||||
type: string
|
||||
username:
|
||||
type: string
|
||||
type: object
|
||||
model.UserGroup:
|
||||
properties:
|
||||
created_at:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
id:
|
||||
type: integer
|
||||
is_system:
|
||||
type: boolean
|
||||
name:
|
||||
type: string
|
||||
updated_at:
|
||||
type: string
|
||||
type: object
|
||||
info:
|
||||
contact: {}
|
||||
description: |-
|
||||
Rill 服务端 HTTP API 文档，所有接口以配置项 api.prefix（默认 /api）为前缀，请求与响应均为 JSON。
|
||||
Swagger 页面：{prefix}/swagger/index.html；OpenAPI JSON：{prefix}/swagger/doc.json。
|
||||
title: Rill API
|
||||
version: "1.0"
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
description: 检查服务与数据库连接状态；数据库不可用时返回 503。
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/api.HealthResponse'
|
||||
"503":
|
||||
description: Service Unavailable
|
||||
schema:
|
||||
$ref: '#/definitions/api.HealthResponse'
|
||||
summary: Health check
|
||||
tags:
|
||||
- system
|
||||
/notes:
|
||||
get:
|
||||
description: 分页查询便签列表，按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。
|
||||
parameters:
|
||||
- description: 页码，默认 1
|
||||
example: 1
|
||||
in: query
|
||||
name: page
|
||||
type: integer
|
||||
- description: 每页数量，默认 20，最大 100
|
||||
example: 20
|
||||
in: query
|
||||
name: page_size
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/api.NoteListResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: List notes
|
||||
tags:
|
||||
- notes
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 创建便签。title 必填且最长 200 字符，content 可选。
|
||||
parameters:
|
||||
- description: 便签内容
|
||||
in: body
|
||||
name: note
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/api.NoteRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
schema:
|
||||
$ref: '#/definitions/model.Note'
|
||||
"400":
|
||||
description: 参数无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Create a note
|
||||
tags:
|
||||
- notes
|
||||
/notes/{id}:
|
||||
delete:
|
||||
description: 按 id 删除便签，成功时返回 204 且无响应体。
|
||||
parameters:
|
||||
- description: 便签 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"204":
|
||||
description: 删除成功
|
||||
"400":
|
||||
description: id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Delete a note
|
||||
tags:
|
||||
- notes
|
||||
get:
|
||||
description: 按 id 查询单个便签。
|
||||
parameters:
|
||||
- description: 便签 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/model.Note'
|
||||
"400":
|
||||
description: id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Get a note
|
||||
tags:
|
||||
- notes
|
||||
put:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 全量更新便签的 title 与 content，字段校验规则同创建。
|
||||
parameters:
|
||||
- description: 便签 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
- description: 便签内容
|
||||
in: body
|
||||
name: note
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/api.NoteRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/model.Note'
|
||||
"400":
|
||||
description: 参数无效或 id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Update a note
|
||||
tags:
|
||||
- notes
|
||||
/user-groups:
|
||||
get:
|
||||
description: 分页查询用户组列表，按 id 升序返回。page 从 1 开始；page_size 取值 1-100，默认 20。
|
||||
parameters:
|
||||
- description: 页码，默认 1
|
||||
example: 1
|
||||
in: query
|
||||
name: page
|
||||
type: integer
|
||||
- description: 每页数量，默认 20，最大 100
|
||||
example: 20
|
||||
in: query
|
||||
name: page_size
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/api.UserGroupListResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: List user groups
|
||||
tags:
|
||||
- user-groups
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 创建用户组。name 必填且唯一（最长 50 字符），description 可选（最长 255 字符）；id 由服务端分配。
|
||||
parameters:
|
||||
- description: 用户组信息
|
||||
in: body
|
||||
name: group
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/api.UserGroupRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
schema:
|
||||
$ref: '#/definitions/model.UserGroup'
|
||||
"400":
|
||||
description: 参数无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"409":
|
||||
description: 用户组名称已存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Create a user group
|
||||
tags:
|
||||
- user-groups
|
||||
/user-groups/{id}:
|
||||
delete:
|
||||
description: 按 id 删除用户组，成功时返回 204 且无响应体。系统内置组或组内仍有用户时返回 409。
|
||||
parameters:
|
||||
- description: 用户组 ID
|
||||
example: 2
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"204":
|
||||
description: 删除成功
|
||||
"400":
|
||||
description: id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"409":
|
||||
description: 系统内置组不可删除或用户组内仍有用户
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Delete a user group
|
||||
tags:
|
||||
- user-groups
|
||||
get:
|
||||
description: 按 id 查询单个用户组，id 0 为内置 admin 组。
|
||||
parameters:
|
||||
- description: 用户组 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/model.UserGroup'
|
||||
"400":
|
||||
description: id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Get a user group
|
||||
tags:
|
||||
- user-groups
|
||||
put:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 更新用户组的 name 与 description，name 必填且唯一。
|
||||
parameters:
|
||||
- description: 用户组 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
- description: 用户组信息
|
||||
in: body
|
||||
name: group
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/api.UserGroupRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/model.UserGroup'
|
||||
"400":
|
||||
description: 参数无效或 id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"409":
|
||||
description: 用户组名称已存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Update a user group
|
||||
tags:
|
||||
- user-groups
|
||||
/users:
|
||||
get:
|
||||
description: 分页查询用户列表（含所属用户组），按 id 倒序返回。page 从 1 开始；page_size 取值 1-100，默认 20。
|
||||
parameters:
|
||||
- description: 页码，默认 1
|
||||
example: 1
|
||||
in: query
|
||||
name: page
|
||||
type: integer
|
||||
- description: 每页数量，默认 20，最大 100
|
||||
example: 20
|
||||
in: query
|
||||
name: page_size
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/api.UserListResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: List users
|
||||
tags:
|
||||
- users
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 创建用户并关联用户组。username、email 唯一，password 长度 6-72；不传 group_ids 时默认加入普通用户组（id
|
||||
1）。
|
||||
parameters:
|
||||
- description: 用户信息
|
||||
in: body
|
||||
name: user
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/api.UserCreateRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
schema:
|
||||
$ref: '#/definitions/model.User'
|
||||
"400":
|
||||
description: 参数无效或用户组不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"409":
|
||||
description: 用户名或邮箱已存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Create a user
|
||||
tags:
|
||||
- users
|
||||
/users/{id}:
|
||||
delete:
|
||||
description: 按 id 删除用户及其用户组成员关系，成功时返回 204 且无响应体。
|
||||
parameters:
|
||||
- description: 用户 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"204":
|
||||
description: 删除成功
|
||||
"400":
|
||||
description: id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Delete a user
|
||||
tags:
|
||||
- users
|
||||
get:
|
||||
description: 按 id 查询用户（含所属用户组）。
|
||||
parameters:
|
||||
- description: 用户 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/model.User'
|
||||
"400":
|
||||
description: id 无效
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Get a user
|
||||
tags:
|
||||
- users
|
||||
put:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 更新用户信息，仅更新请求中提供的字段。传 group_ids 会整体替换用户组；password 非空时重置密码。
|
||||
parameters:
|
||||
- description: 用户 ID
|
||||
example: 1
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
- description: 待更新字段
|
||||
in: body
|
||||
name: user
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/api.UserUpdateRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/model.User'
|
||||
"400":
|
||||
description: 参数无效、id 无效或用户组不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"404":
|
||||
description: 记录不存在
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/api.ErrorResponse'
|
||||
summary: Update a user
|
||||
tags:
|
||||
- users
|
||||
swagger: "2.0"
|
||||
Reference in New Issue
Block a user