文章目录
- 1. 接口文档
- 2. Open API
- 3. Swagger 简介
- 4. Springfox
- 5. Swagger 基本用法
- 6. Swagger-UI使用
- 7. Swagger配置
1. 接口文档
- 接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。
- 很多人员会抱怨别人写的接口文档不规范，不及时更新。但是当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。
- 如果接口文档可以实时动态生成就不会出现上面问题。
- Swagger可以完美的解决上面的问题。
2. Open API
- Open API规范(OpenAPI Specification)以前叫做Swagger规范，是REST API的API描述格式。
- Open API文件允许描述整个API，包括：
- 每个访问地址的类型。POST或GET。
- 每个操作的参数。包括输入输出参数。
- 认证方法。
- 连接信息，声明，使用团队和其他信息。
- Open API规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。
- OpenAPI规范（OAS）为REST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。
- 文档生成工具可以使用OpenAPI定义来显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。
- 源码和说明参照：
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument
3. Swagger 简介
- Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。
- Swagger工具包括的组件：
- Swagger Editor ：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。
- Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。
- Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
- Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
- Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
- 使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。
4. Springfox
- 使用Swagger时如果碰见版本更新或迭代时，只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。
- Marty Pitt编写了一个基于Spring的组件swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。
- Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。
- Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。
- 所以在实际开发中，都是直接使用spring-fox。
- 官网地址
http://springfox.github.io/springfox/ - 官方源码
https://github.com/springfox/springfox
- 官网地址
5. Swagger 基本用法
注意：SpringBoot 版本和 Swagger 版本有些兼容性的问题，使用时确保Boot版本是否兼容了Swagger的版本
- 编写SpringBoot项目，SpringBoot版本 2.5.6
编写SpringBoot项目，项目中controller中包含一个Handler，测试项目，保证程序可以正确运行。
@RestController
public class MyController {
@PostMapping("/post")
public String post(){
return "post";
}
@GetMapping("/get")
public String get(String a, String b) {
return "get";
}
@RequestMapping("/req")
public String req(String m) {
return "req";
}
}
- 导入Spring-fox依赖
- 在项目的pom.xml中导入Spring-fox依赖。版本为2.9.2，所以导入的依赖也是这个版本。其中springfox-swagger2是核心内容的封装。springfox-swagger-ui是对swagger-ui的封装。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 添加注解
- 在SpringBoot的启动类中添加
@EnableSwagger2注解。
添加此注解后表示对当前项目中全部控制器进行扫描。应用Swagger2
@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
- 访问swagger-ui
- 启动项目后在浏览器中输入
http://ip:port/swagger-ui.html即可以访问到swagger-ui页面，在页面中可以可视化的进行操作项目中所有接口。
6. Swagger-UI使用
-
访问swagger-ui.html后可以在页面中看到所有需要生成接口文档的控制器名称。
-
每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping进行映射，将显示下面的所有请求方式。如果使用@PostMapping将只有Post方式可以能访问，下面也就只显示Post的一个请求。
-
也可以看到在 controller 中定义的请求方法类型与ui界面的请求类型是对应的
-
点击某个请求方式中 try it out
-
会出现界面要求输入的值。输入完成后点击Execute按钮
-
会出现Request URL以及不同状态码响应回来的结果。
7. Swagger配置
- 可以在项目中创建SwaggerConfig，进行配置文档内容。
- 配置基本信息
Docket：摘要对象，通过对象配置描述文件的信息。
apiInfo:设置描述文件中info。参数类型ApiInfo
select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
ApiInfoBuilder：ApiInfo构建器。
