api文档格式

api文档格式？

API文档的格式可以因不同需求和使用场景而有所差异。下面是一些常见的API文档格式：
1. OpenAPI规范（前身为Swagger）：使用YAML或JSON格式的文档，具有规范的结构和约定，可以描述API的路径、参数、响应、错误等信息。OpenAPI规范还可以生成交互式文档和服务器存根代码。
2. RAML（RESTful API Modeling Language）：使用YAML格式的文档，具有类似于OpenAPI的功能，可以描述API的路径、参数、响应等信息。
3. API Blueprint：使用Markdown格式的文档，具有简洁的语法，可以描述API的路径、参数、响应等信息。可以使用特定工具将API Blueprint转换为交互式文档或其他格式。
4. HTML或Markdown文档：使用HTML或Markdown格式编写的文档，可以详细描述API的路径、参数、响应等信息。可以使用静态网页生成工具将其生成为静态站点。
以上只是一些常见的API文档格式，具体格式的选择还应根据团队的偏好、开发工具的支持以及目标用户的需求来确定。

API文档通常采用一种结构化的格式，包括以下内容：API的基本信息、请求和响应的数据结构、请求方法和参数、错误码和错误信息、示例代码和使用说明等。

常见的API文档格式包括OpenAPI（Swagger）、RAML、API Blueprint等。这些格式提供了一种标准化的方式来描述API的功能和使用方法，使开发者能够更轻松地理解和使用API。

同时，API文档还应该具备清晰的结构、易于搜索和导航的特点，以便开发者能够快速找到所需的信息。

可用格式为:JSON-LD,GraphQL,JSON,JSON:API,HAL,XML,YAML,CSV,HTML(API文档)。

tn : totalNumber => 总条数

sn : sizeNumber => 分页阈值

cn : currentNumber => 当前页数

pn : pageNumber => 总页数

q : query => 查询参数

asc: 1/0 => 升序/降序

code: 业务约定,0为正确,其他为错误

orderBy: key => 以 key 作为排序参数

需要注意的点

所有资源 ID 对当前接口返回统一命名为 id

数据库操作 下划线 连接所有对外字段，全部改为小驼峰