Rest API接口说明| swagger、HTML、postman

1. 三种描述方式

在后端设计好接口之后，需要获得Rest API接口的说明文档和调试接口，主要方式如下：

类型	说明
swagger版本	由代码中的swagger注释生成的json文件
HTML版本	将swagger.json文件插入yapi，生成HTML版本的说明文档，方便阅读
postman版本	postman可保存输入参数，来调用接口

2. swagger.json的生成

1. 使用swagger对代码进行注释

2. 部署项目后，找到Swagger API在线地址

3. 点击http://ip:port/user/v3/api-docs ，获得json格式的说明文档

4. 复制json文件并将其格式化后保存

3. HTM文档的生成方式

• 使用yapi生成HTML文档

• yapi在本项目中主要便于生成html文档。

  • 在stage环境中使用的是https，或者采用证书方式登录，yapi就不便于使用，需要使用postman工具来进行接口调试。
  • yapi无需下载到本地，登录https://yapi.baidu.com/即可实现文档生成功能

• 这里yapi不支持swaggerV3版本，在yapi中导入swaggerV3版本，则返回值全部为空。则在swagger.json生成的过程中，将v3更换为v2。获得swagger v2版本的json文档。

在yapi中具体操作步骤：

1. 在yapi中添加分组

2. 在分组中添加项目

3. 在项目中导入swagger v2版本的json文档

4. yapi中数据导出为html格式

3. Postman相应说明

• Postman可以从swagger.json直接导入
• yapi不支持postman生成的collectionv2版本，只支持v1版本