目前是把 API 写到 notion 里,可以放代码,也可以添加文字说明。
展示 API 的格式用过 Table 、JSON 、YAML
这是 JSON 的例子:
Update a specific collection
{
"endpoint": "/collection/update?collection_id=uuid",
"method": "POST",
"header": {
"Authorization": "Bearer token"
},
"body": {
"name": "string (required)",
"description": "string (optional)"
},
"response": [
{
"code": 200,
"message": "Success",
"data": [
{
"id": "cfcb92e9-9455-4756-94b4-5e93d36941b0",
"owner": "test",
"name": "test",
"description": "",
"created_at": "2023-06-24T08:09:44.585915",
"updated_at": "2023-06-25T07:17:28.229913"
}
]
},
{
"code": 400,
"message": "Bad Request / Invalid Collection ID / Invalid Name"
},
{
"code": 401,
"message": "Email Verification Required"
},
{
"code": 401,
"message": "Unauthorized"
}
]
}
Table 格式:
[td]Path[/td]
[td]Method[/td]
[td]Params[/td]
[td]Header[/td]
[td]Body[/td]
[td]Response[/td]
[td]Comment[/td]
/api/foo
GET
-
-
-
200 OK
Fetches data from /api/foo
/api/bar
POST
key
-
JSON
201 Created
Creates a new resource
/api/baz
PUT
id
-
JSON
200 OK
Updates resource with id
个人喜欢 JSON 格式整理 API ,能展示的信息更多。但往往几个 API 就能写好几页,有大部分是重复的,但又不太好省略。
不知道大家有没有更好的方法或工具,可以方便查阅、管理 API ?
感谢!