用过 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 ?
感谢!
这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。
V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。
V2EX is a community of developers, designers and creative people.