docs: describe login-only spaces and the 8.0.0 contract [CI]
This commit is contained in:
justme committed
1 parent
8233369cd4
commit
12980ba6fe
7 files changed
+68
-106
No files matched your search
+29
-66
@@ -1,7 +1,7 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: WebDrop API
|
||||
version: 7.0.0
|
||||
version: 8.0.0
|
||||
servers:
|
||||
- url: /api/v1
|
||||
|
||||
@@ -9,7 +9,6 @@ tags:
|
||||
- name: server
|
||||
- name: channel
|
||||
- name: join
|
||||
- name: guest
|
||||
- name: frame
|
||||
- name: item
|
||||
- name: share
|
||||
@@ -94,7 +93,7 @@ paths:
|
||||
required: false
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/Role'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -123,7 +122,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -161,7 +160,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -199,7 +198,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -233,7 +232,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -271,7 +270,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -305,7 +304,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -343,7 +342,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -377,7 +376,7 @@ paths:
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- $ref: '#/components/parameters/RoleWriter'
|
||||
- $ref: '#/components/parameters/Endpoint'
|
||||
- $ref: '#/components/parameters/Account'
|
||||
- name: Authorization
|
||||
in: header
|
||||
schema: { type: string }
|
||||
@@ -603,7 +602,7 @@ paths:
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
responses:
|
||||
'200':
|
||||
description: 成员列表
|
||||
@@ -679,7 +678,7 @@ paths:
|
||||
创建者的账号自动成为该频道 owner,其终端自动入席。
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/Captcha' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
@@ -703,7 +702,7 @@ paths:
|
||||
get:
|
||||
tags: [channel]
|
||||
summary: 读取频道信息(不占成员名额)
|
||||
description: 任意角色可调用。`members_used` 表示唯一账号成员数加匿名访客终端数，不是设备数。
|
||||
description: 需要账号会话。`members_used` 表示唯一账号成员数，不是设备数。
|
||||
security: [{ bearer: [] }]
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
@@ -760,13 +759,12 @@ paths:
|
||||
tags: [join]
|
||||
summary: 加入频道
|
||||
description: |
|
||||
幂等。登录账号只登记成员关系:同一账号的多台设备不增加人数,也不登记终端,此后仅凭账号会话鉴权(`X-WD-Endpoint` 可省略)。
|
||||
未登录访客登记一个终端(`X-WD-Endpoint` 必填),每个终端单独计一个成员名额。成员名额已满返回 403 `members_full`。
|
||||
读取频道信息和 owner 管理接口不占名额;访客访问频道内容前必须已加入,否则 403 `not_joined`。
|
||||
幂等。必须带账号会话(没有则 401 `account_required`)。只登记成员关系:同一账号的多台设备不增加人数,此后仅凭账号会话鉴权。
|
||||
成员名额已满返回 403 `members_full`。读取频道信息和 owner 管理接口不占名额;访问频道内容前必须已加入,否则 403 `not_joined`。
|
||||
security: [{ bearer: [] }]
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
requestBody:
|
||||
required: false
|
||||
content:
|
||||
@@ -785,44 +783,6 @@ paths:
|
||||
'403': { $ref: '#/components/responses/Error' }
|
||||
'404': { $ref: '#/components/responses/Error' }
|
||||
|
||||
/channels/{id}/guests:
|
||||
get:
|
||||
tags: [guest]
|
||||
summary: 查看访客(所有者)
|
||||
description: 只列未登录访客的终端。账号成员按用户管理(`/members`、`/invitations`),其设备不对外列出。
|
||||
security: [{ bearer: [] }]
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/RoleOwner' }
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items: { $ref: '#/components/schemas/Guest' }
|
||||
'403': { $ref: '#/components/responses/Error' }
|
||||
|
||||
/channels/{id}/guests/{endpointHash}:
|
||||
delete:
|
||||
tags: [guest]
|
||||
summary: 移除访客(所有者)
|
||||
description: 移除该访客终端并禁止它再加入;被移除终端后续请求返回 `not_joined`。账号成员改用 `DELETE /invitations/{username}`。
|
||||
security: [{ bearer: [] }]
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- name: endpointHash
|
||||
in: path
|
||||
required: true
|
||||
description: 访客终端标识,即 `base64url(SHA-256(S))`
|
||||
schema: { $ref: '#/components/schemas/Base64Url' }
|
||||
- { $ref: '#/components/parameters/RoleOwner' }
|
||||
responses:
|
||||
'204': { description: 已移除 }
|
||||
'403': { $ref: '#/components/responses/Error' }
|
||||
'404': { $ref: '#/components/responses/Error' }
|
||||
|
||||
/channels/{id}/frames:
|
||||
post:
|
||||
tags: [frame]
|
||||
@@ -835,7 +795,7 @@ paths:
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/RoleWriter' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
- name: X-WD-Max-Downloads
|
||||
in: header
|
||||
required: false
|
||||
@@ -875,7 +835,7 @@ paths:
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
- name: from
|
||||
in: query
|
||||
required: false
|
||||
@@ -918,7 +878,7 @@ paths:
|
||||
|
||||
**服务端 → 客户端**
|
||||
- 二进制消息:一条日志记录(`seq ‖ kind ‖ body`)。
|
||||
- 文本消息(JSON):`{"t":"hb","seq":N}` 心跳(每 20 秒);`{"t":"settings"}` 设置变更;`{"t":"members"}` 成员/访客变更。
|
||||
- 文本消息(JSON):`{"t":"hb","seq":N}` 心跳(每 20 秒);`{"t":"settings"}` 设置变更;`{"t":"members"}` 成员变更。
|
||||
|
||||
客户端 45 秒收不到任何消息应判定死链,以指数退避(1~30 秒)加抖动重连,并带 `from=last_seq+1`。
|
||||
上传不走 WebSocket,仍用 `POST /frames`。
|
||||
@@ -950,7 +910,7 @@ paths:
|
||||
parameters:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
- name: from
|
||||
in: query
|
||||
required: false
|
||||
@@ -981,7 +941,7 @@ paths:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/ItemId' }
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
- name: from
|
||||
in: query
|
||||
required: false
|
||||
@@ -1009,7 +969,7 @@ paths:
|
||||
- { $ref: '#/components/parameters/ChannelId' }
|
||||
- { $ref: '#/components/parameters/ItemId' }
|
||||
- { $ref: '#/components/parameters/Role' }
|
||||
- { $ref: '#/components/parameters/Endpoint' }
|
||||
- { $ref: '#/components/parameters/Account' }
|
||||
responses:
|
||||
'204': { description: 已删除 }
|
||||
'403': { $ref: '#/components/responses/Error' }
|
||||
@@ -1243,6 +1203,12 @@ components:
|
||||
required: true
|
||||
description: 条目 id,16 字节 base64url
|
||||
schema: { $ref: '#/components/schemas/Base64Url' }
|
||||
Account:
|
||||
name: X-WD-Account
|
||||
in: header
|
||||
required: true
|
||||
description: 账号会话令牌。频道与空间只接受已登录账号,缺少或失效返回 401 `account_required`。
|
||||
schema: { type: string }
|
||||
Role:
|
||||
name: X-WD-Role
|
||||
in: header
|
||||
@@ -1263,7 +1229,7 @@ components:
|
||||
name: X-WD-Endpoint
|
||||
in: header
|
||||
required: false
|
||||
description: 终端密钥 `S` 的 base64url,仅存本地。只有未登录访客必填;登录账号以 `X-WD-Account` 会话鉴权,可省略。
|
||||
description: 终端密钥 `S` 的 base64url,仅存本地。只用于便捷分享(未登录的创建者与读者);频道与空间使用 `X-WD-Account` 会话,不需要它。
|
||||
schema: { $ref: '#/components/schemas/Base64Url' }
|
||||
ShareEndpoint:
|
||||
name: X-WD-Endpoint
|
||||
@@ -1410,8 +1376,5 @@ components:
|
||||
JoinResult:
|
||||
$ref: '../contracts/api.schemas.json#/$defs/JoinResult'
|
||||
|
||||
Guest:
|
||||
$ref: '../contracts/api.schemas.json#/$defs/GuestInfo'
|
||||
|
||||
AppendResult:
|
||||
$ref: '../contracts/api.schemas.json#/$defs/AppendResult'
|
||||
Reference in new issue
Block a user