用OpenAPI3在SwaggerHub编写API接口文档

用OpenAPI3在SwaggerHub编写API接口文档

工具说明

1. 什么是OpenAPI3和SwaggerHub？

• Swagger 是一款用来设计符合RESTful API标准的接口文档和管理API文档的工具，可以用来编写API文档、测试API和根据API自动生成代码原型等，是目前最受欢迎的API设计工具之一。而SwaggerHub则是一个提供这种服务的一个平台，提供在线的网页服务和离线下载的版本。
• OpenAPI是一个社区驱动的、开放的API接口规范，是Linux基础协作项目中的开放规范。OpenAPI规范（OAS）为RESTAPI定义了一个标准的、与编程语言无关的接口描述，它允许人类和计算机在不需要访问源代码、附加文档或检查网络流量的情况下发现和理解服务的功能。当通过OpenAPI正确定义时，使用者可以用最少的实现逻辑理解和与远程服务交互。而OpenAPI3则是第三代OpenAPI接口规范。

使用SwaggerHub

1. 打开swaggerhub官网登录，在线编辑器地址，先注册相应账号，有github账号者可直接登录。

2. 进入个人界面后创建新的API

3. 选择OpenAPI标准版本，这里使用OpenAPI3，选择模板，自动mock API。

4. 界面如下，左边是API索引列表，中间是代码区，右边是API UI显示区

5. swaggerAPI文档代码可以用yaml或者json语法来编写，代码规范OpenAPI3规范。

6. Swagger UI还提供了即时测试的功能，点击try it out 即可执行测试，获取发送报文格式以及放回返回结果。