724 lines
18 KiB
YAML
724 lines
18 KiB
YAML
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"
|