各位是如何整理 API 的？

[Wanten]

用过 postman ，可以把 api 保存到上面，而且可以附带实例。但有时候觉得不太方便，加载、浏览问题。

目前是把 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 格式：

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 ？

感谢！

[wind1986]

用 swagger, 然后导出

[jaylee4869]

https://petstore.swagger.io/

[tsanie]

OAS 3.0 ，我喜欢用 redoc 做呈现，好看些

[jiammbeyond]

yapi