用过 postman ,可以把 api 保存到上面,而且可以附带实例。但有时候觉得不太方便,加载、浏览问题。
目前是把 API 写到 notion 里,可以放代码,也可以添加文字说明。
展示 API 的格式用过 Table 、JSON 、YAML
这是 JSON 的例子:
{
"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 格式:
Path | Method | Params | Header | Body | Response | Comment |
---|---|---|---|---|---|---|
/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 ?
感谢!
1
wind1986 2023-07-20 10:36:31 +08:00 1
用 swagger, 然后导出
|
2
jaylee4869 2023-07-20 10:41:13 +08:00 1
|
3
tsanie 2023-07-20 11:03:27 +08:00 1
OAS 3.0 ,我喜欢用 redoc 做呈现,好看些
|
4
jiammbeyond 2023-07-20 15:44:34 +08:00
yapi
|