Swagger总结
目录
简介：
openAPI
Springfox：
简介
Springfox的使用
SwaggerUI的使用
Swagger配置
设置扫描的包
设置范围
Swagger常用注解：
控制类、方法生成接口信息
@ApiParam
@ApiModel
@ApiModelProperty
@ApiIgnore
@ApiImplicitParam
部分图片来自百战程序员
简介：
接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。很多人员会抱怨别人写的接口文档不规范，不及时更新。如果接口文档可以实时动态生成就不会出现上面问题，Swagger可以完美地解决上面的问题。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful 风格的 Web 服务，可用于接口的文档在线自动生成以及功能测试。
openAPI
Open API 是什么：Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范，是REST API 的 API 描述格式。Open API 文件允许描述整个 API，包括：
- 每个访问地址的类型。POST 或 GET
- 每个操作的参数。包括输入输出参数
- 认证方法
- 连接信息，声明，使用团队和其他信息。
Open API 规范可以使用YAML或 JSON格式进行编写，这样更利于我们和机器进行阅读。
Swagger和Open API
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 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码
Springfox：
简介
使用 Swagger 时如果碰见版本更新，只需要更改Swagger的描述文件即可。但是在频繁地更新项目版本时很多开发人员认为即使修改描述文件（yml 或 json）也有一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也就失去了意义。
由于Spring的流行，Marty Pitt 编写了一个基于Spring 的组件swagger-springmvc。Spring-fox 就是根据这个组件发展而来的全新项目。Spring-fox 是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。Spring-fox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。所以在实际开发中，都是直接使用 spring-fox。官网地址：
GitHub - springfox/springfox: Automated JSON API documentation for API's built with Spring
Springfox的使用
1、创建SpringBoot项目，添加spring-fox依赖
在项目的pom.xml中导入Spring-fox依赖。选择版本2.9.2，所以导入的依赖也是这个版本。其中 springfox-swagger2 是核心内容的封装。springfox-swagger-ui 是对 swagger-ui 的封装。
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
2、创建实体类
public class People {
private int id;
private String name;
private String address;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAddress() {
return address;
}
public void setAddress(String address) {
this.address = address;
}
}
3、创建controller
@RestController
@RequestMapping("/people")
public class MyController {
@RequestMapping("/getPeople")
public People getPeople(int id,String name){
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress("深圳");
return people;
}
}
4、在启动类中添加@EnableSwagger2注解，添加此注解后表示对当前项目中全部控制器进行扫描，应用Swagger2。
@SpringBootApplication
@EnableSwagger2
public class SwaggerBlogApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerBlogApplication.class, args);
}
}
访问 swagger-ui
启动项目后在浏览器中输入 http://IP:port/swagger-ui.html即可以访问到 swagger-ui 页面，在页面中可以可视化的进行操作项目中所有接口。
SwaggerUI的使用
访问 swagger-ui.html 可以在页面中看到所有需要生成接口文档的控制器名称。
每个控制器包含该控制器下所有的方法及访问方式。如果使用的是@RequestMapping 进行映射，将显示下面的所有请求方式。如果使用@PostMapping 将只有 Post 方式可以能访问，下面也就只显示Post 的一个。
点击某个请求方式中 try it out
输入参数值，完成后点击 Execute 按钮
下面会出现 Request URL 以及响应结果。
Swagger配置
可以在项目中创建 SwaggerConfig，进行配置文档内容
@Configuration
public class SwaggerConfig{
@Bean
public Docket getDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.build();
}
private ApiInfoswaggerDemoApiInfo(){
return new ApiInfoBuilder()
.contact(new Contact("北京尚学堂", "http://www.bjsxt.com","[email protected]"))
//文档标题
.title("这里是Swagger的标题")
//文档描述
.description("这里是Swagger的描述")
//文档版本
.version("1.0.0")
.build();
}
}
- 配置基本信息
| 配置项 |
含义 |
| Docket |
摘要对象，通过对象配置描述文件的信息。 |
| apiInfo |
设置描述文件中 info，参数类型 ApiInfo |
| select() |
返回 ApiSelectorBuilder 对象，通过对象调用 build()可以创建 Docket 对象 |
| ApiInfoBuilder |
ApiInfo 构建器 |
显示效果如下：
设置扫描的包
- 设置扫描的包
可以通过 apis()方法设置哪个包中内容被扫描
@Bean
public Docket getDocket() {
return new Docket(DocumentationType. SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.itbaizhan.swagger_blog.controller"))
.build();
}
设置范围
通过下面的代码
public ApiSelectorBuilder paths(Predicate
可以设置满足什么样规则的 url 被生成接口文档。可以使用正则表达式进行匹配。
下面例子中表示只有以/demo/开头的 url 才能被 swagger 生成接口文档。
@Bean
public Docket getDocket(){
return new Docket(DocumentationType. SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.paths(allowPaths())
.build();
}
private Predicate allowPaths(){
return or(regex("/demo/.*"));
}
如何希望全部扫描可以使用
paths(PathSelectors.any())
Swagger常用注解：
控制类、方法生成接口信息
- @Api
| 注解名称 |
参数 |
含义 |
| @Api |
类上注解。控制整个类生成接口信息的内容 |
|
| tags |
类的名称，可以有多个值，多个值表示多个副本 |
|
| description |
描述 |
代码示例如下：
@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {
@PostMapping("/getPeople")
public People getPeople(int id,String name){
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress("深圳");
return people;
}
}
在 swagger-ui.html 中显示效果
- @ApiOperation
| 注解名称 |
参数 |
含义 |
| @ApiOperation |
写在方法上，对方法进行总体描述 |
|
| value |
接口描述 |
|
| notes |
提示信息 |
代码示例：
@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {
@ApiOperation(value = "获取人类",notes = "获取人类的信息")
@PostMapping("/getPeople")
public People getPeople(int id,String name){
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress("深圳");
return people;
}
}
在 swagger-ui 中显示效果
@ApiParam
- ApiParam
| 注解名称 |
参数 |
含义 |
| @ApiParam |
写在控制器方法参数前面。用于对参数进行描述或说明是否为必添项等说明 |
|
| name |
参数名称 |
|
| value |
参数描述 |
|
| required |
是否是必须 |
在代码中示例：
@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {
@ApiOperation(value = "获取人类",notes = "获取人类的信息")
@PostMapping("/getPeople")
public People getPeople(int id,@ApiParam(value = "姓名",required = true) String name){
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress("深圳");
return people;
}
}swagger-ui 显示效果如下：
@ApiModel
- ApiModel
| 注解名称 |
参数 |
含义 |
| @ApiModel |
是类上注解，主要应用 Model，也就是说这个注解一般都是写在实体类上 |
|
| value |
名称 |
|
| description |
描述 |
代码示例：
@ApiModel(value = "人类",description = "描述")
public class People {......}swagger-ui.html 效果展示
@ApiModelProperty
| 注解名称 |
参数 |
含义 |
| @ApiModelProperty |
一般用于实体类方法、属性的说明 |
|
| value |
字段说明 |
|
| name |
重写属性名 |
|
| required |
是否必须 |
|
| example |
示例内容 |
|
| hidden |
是否隐藏 |
代码示例：
@ApiModel(value = "人类",description = "描述")
public class People {
private int id;
@ApiModelProperty(value = "姓名",required = true,example = "张三")
private String name;
private String address;
......
} 
@ApiIgnore
| 注解名称 |
含义 |
| @ApiIgnore |
用于方法或类或参数上，表示这个方法或类被忽略 |
@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
@ApiIgnore
public class MyController {
@ApiOperation(value = "获取人类",notes = "获取人类的信息")
@PostMapping("/getPeople")
public People getPeople(int id,@ApiParam(value = "姓名",required = true) String name){
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress("深圳");
return people;
}
}
@ApiImplicitParam
| 注解名称 |
参数 |
含义 |
| @ApiImplicitParam |
用在控制器方法上，表示单独的请求参数，总体功能和@ApiParam 类似。 |
|
| value |
对接口中的参数进行简单必要的描述 |
|
| name |
描述接口中参数的名称 |
|
| required |
是否必须 |
|
| paramType |
接口中的参数应该用在哪个地方，常用的位置有：header、query 、path |
|
| dataType |
接口中参数的类型 |
代码示例：
@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
//@ApiIgnore
public class MyController {
@ApiOperation(value = "获取人类",notes = "获取人类的信息")
@PostMapping("/getPeople")
@ApiImplicitParam(value = "编号",name = "id")
public People getPeople(int id, @ApiParam(value = "姓名",required = true) String name){
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress("深圳");
return people;
}
}
swagger-ui.html 效果展示
如果希望在方法上配置多个参数时，使用@ApiImplicitParams 进行配置。示例如下：
@ApiImplicitParams(value={@ApiImplicitParam(name="id",value="编号",required=true),@ApiImplicitParam(name="name",value="姓名",required=true)})