接口文档管理系列 OpenAPI规范及Swagger工具集
接口设计及文档管理系列 各个工具及概念介绍
- OpenAPI
- OpenAPI规范
- OpenAPI规范的历史
- OpenAPI描述文档格式
- OpenAPI 2.0描述文档
- OpenAPI 3.0描述文档
- Swagger
- Swagger UI
- Swagger Editor
- Swagger Codegen
- Swagger Hub
- Swagger Inspector
- Springfox Swagger 根据代码（注解）生成接口文档
- Springdoc
- Swagger 功能扩展插件 Knife4j 生成离线文档
- Hypertext Transfer Protocol (HTTP) Status Code Registry
- 导读
OpenAPI
在互联网时代，把网站的服务封装成一系列计算机易识别的数据接口开放出去，供第三方开发者使用，这种行为就叫做开放网站的API，与之对应的，所开放的API就被称作OpenAPI。
OpenAPI规范
什么是OpenAPI规范？
OpenAPI规范（以前称为Swagger规范）是定义RESTful接口的世界标准。OAS使开发人员能够设计与技术无关的API接口，从而构成其API开发和使用的基础。
OpenAPI规范的简称为：OAS
OpenAPI规范的历史
| Version | Date | Notes |
|---|---|---|
| 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 |
| 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 |
| 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification |
| 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification |
| 3.0.0-rc0 | 2017-02-28 | Implementer’s Draft of the 3.0 specification |
| 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative |
| 2.0 | 2014-09-08 | Release of Swagger 2.0 |
| 1.2 | 2014-03-14 | Initial release of the formal document. |
| 1.1 | 2012-08-22 | Release of Swagger 1.1 |
| 1.0 | 2011-08-10 | First release of the Swagger Specification |
OpenAPI是规范的正式名称。该规范的开发是由OpenAPI Initiative推动的，该倡议涉及更多来自技术领域不同领域的30个组织-包括Microsoft，Google，IBM和CapitalOne。领导Swagger工具开发的公司Smartbear Software也是OpenAPI Initiative的成员，帮助领导了规范的发展。
OpenAPI规范Github上的标准文档
OpenAPI描述文档格式
OpenAPI描述文档可以是JSON或者YAML格式的其中一种。
建议将根OpenAPI文档命名为openapi.json或openapi.yaml。
格式
符合OpenAPI规范的OpenAPI文档本身就是JSON对象，可以用JSON或YAML格式表示。
例如，如果一个字段具有数组值，则将使用JSON数组表示形式：
{
“字段”：[ 1，2，3 ]
}
规范中的所有字段名称均区分大小写。
该模式公开两种类型的字段：固定字段（具有声明的名称）和模式字段（Patterned），它们为字段名称声明正则表达式模式。
模式字段必须在包含的对象内具有唯一的名称。
为了保留在YAML和JSON格式之间往返的能力，建议使用YAML 1.2版以及一些其他约束：
定义
OpenAPI文件
定义或描述API的一个文档（或一组文档）。OpenAPI定义使用并符合OpenAPI规范。
详细的说明请看OpenAPI定义手册
Swagger specification
OpenAPI 2.0描述文档
OpenAPI 3.0描述文档
Swagger
OAS和Swagger
您不能不谈Swagger就谈OAS。SmartBear的Swagger项目是OAS的原始基础，它由Swagger规范和Swagger工具组成。Swagger社区负责构建工具的使用，以在整个API生命周期中充分利用OAS的功能。
Swagger是什么？它能干什么？
Swagger提供了最简单易用的工具，以充分利用OpenAPI规范（OAS）的所有功能。
Swagger是与用于实现OpenAPI规范的一些最著名，使用最广泛的工具相关联的名称。Swagger工具集包括开源工具，免费工具和商业工具的组合，可在API生命周期的不同阶段使用。
包括并不限于
- API设计
- API开发
- API文档
- API测试
Swagger工具集介绍
Swagger UI
提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
使用频度：高
Swagger Editor
: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
然后，文档生成工具可以使用OpenAPI定义来显示API，代码生成工具可以使用各种编程语言来生成服务器和客户端，测试工具以及许多其他用例也可以使用OpenAPI定义。
Swagger 官方提供的在线 Editor
你也可以选择自己用Docker部署一个Swagger Editor
使用频度：一般
Swagger Codegen
Swagger Codegen是一个开源代码生成器，可直接从Swagger定义的RESTful API构建服务器存根和客户端SDK。
Swagger Codegen的源代码可以在GitHub中找到。
使用频度：低
通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在Swagger Editor中在线生成。
Swagger Codegen Documentation
Swagger Codegen 首页
Swagger Hub
适用于使用OpenAPI规范的团队和个人的设计和文档平台。
在您的组织中开发的API越多，就越需要建立通用的设计准则。SwaggerHub配备了内置的API标准化，使您的API符合您的组织设计准则。企业架构师可以确保团队成功遵循设计模式。
SwaggerHub用于标准化设计
Swagger Hub 首页
使用需要登陆哦（用github账号也可以）
使用频度：中等
Swagger Inspector
Swagger Inspector用于测试API
在开发过程中验证功能
不断要求开发人员仔细检查其API和端点是否在开发过程中按预期工作。Swagger Inspector提供了轻松检查API请求响应并确保它们按预期工作的功能。
使用频度：低
Springfox Swagger 根据代码（注解）生成接口文档
对于许多开发来说，编写这个OpenAPI的yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。
使用频度：高
Springdoc
Springdoc与OpenAPI 3兼容，并支持Spring WebFlux，而且可以和SpringFox共存。
下面两个图是在同一个项目中的swagger-ui中的截图
使用频度：高
Swagger 功能扩展插件 Knife4j 生成离线文档
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j
生成的接口文档
使用频度：高
乍一看，接口文档的管理用Swagger的工具挺多的，你可能会想到学习成本的问题，但是并不是上面说的所有工具都要使用的，我已经在上面标注了使用频度，频度低的完全可以不使用。
我的推荐是
SSM项目使用 SpringFox + Swagger-UI + Knife4j + Swagger Editor
SpringBoot项目使用 Springdoc + Swagger-UI + Knife4J + Swagger Editor
上面的搭配基本可以满足大部分场景了。
后面我会对这些模块展开介绍并给出Demo。
Hypertext Transfer Protocol (HTTP) Status Code Registry
1xx：信息性-接收到请求，继续处理
2xx：成功-已成功接收，理解并接受了操作
3xx：重定向-必须采取进一步的操作才能完成请求
4xx：客户端错误-请求包含错误的语法或无法被满足
5xx：服务器错误-服务器无法满足看似有效的请求
HTTP Status Codes
导读
接口文档管理系列 Spring MVC框架整合Swagger
接口文档管理系列 Springboot集成springdoc