swagger
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格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码
使用
maven
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
启动类
package com.bjsxt.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*
* EnableSwagger2 - 是springfox提供的一个注解，代表swagger2相关技术开启，
* 会扫描当前类所在包，及子包中所有的类型中的注解。做swagger文档的定制
*/
@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
访问地址
浏览器访问：http://localhost:8080/swagger-ui.html
Swagger配置
可以在项目中创建SwaggerConfig，进行配置文档内容。
配置基本信息
Docket：摘要对象，通过对象配置描述文件的信息。
apiInfo:设置描述文件中info。参数类型ApiInfo
select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
ApiInfoBuilder：ApiInfo构建器。
设置扫描的包
可以通过apis()方法设置哪个包中内容被扫描
package com.bjsxt.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import javax.print.Doc;
@Configuration
public class SwaggerConfiguration {
/**
* 创建Docket类型的对象，并使用spring管理。
* Docket是Swagger中的全局配置对象
* @return
*/
@Bean
public Docket docket(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//API帮助文档的描述信息 information
ApiInfo apiInfo = new ApiInfoBuilder()
.contact(//配置swagger文档主体内容
new Contact(
"北京尚学堂 - HHH",//是文档的发布者名称
"http://www.bjsxt.com",//是文档发布者的网站地址，企业网站
"admin@bjsxt.com"))//文档发布者的电子邮箱
.title("Swagger框架学习帮助文档")
.description("Swagger框架学习帮助文档详细描述-Swagger框架是一个用于开发RestAPI帮助文档的框架")
.version("1.1")
.build();
//给docket上下文配置api描述信息
docket.apiInfo(apiInfo);
docket
.select()//获取Docket中的选择器。返回是ApiSelectorBuilder。构建选择器的。如：扫描什么包的注解
.apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller"));//设定扫描哪个包（包含子包）中的注解
return docket;
}
}
自定义注解设置不需要生成接口文档的方法
自定义注解
注解名称随意
package com.bjsxt.swagger.anno;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* @Target - 描述当前的注解可以定义在什么资源上
* 属性 value
* - 定义具体的资源。包括：
* - ElementType.METHOD 可以定义在方法上
* - ElementType.TYPE 可以定义在类型上
* - ElementType.FIELD 可以定义在属性上
* - ElementType.PARAMETER 可以定义在方法参数上
* @Retention - 当前注解在什么时候有效
* 属性 value
* - 定义具体的生效标记
* - RetentionPolicy.RUNTIME - 运行时有效
* - RententionPolicy.SOURCE - 源码中有效
* - RententionPolicy.CLASS - 字节码有效
*/
@Target(value={ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation4Swagger {
// 自定义注解中的属性。相当于@MyAnnotation4Swagger(value="")
String value() default "";
}
添加规则
通过public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。
public static <T> Predicate<T> not(Predicate<T> predicate) :表示不允许的条件。
package com.bjsxt.swagger.config;
import com.bjsxt.swagger.anno.MyAnnotation4Swagger;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import javax.print.Doc;
import com.google.common.base.Predicates;
import springfox.documentation.builders.RequestHandlerSelectors;
@Configuration
public class SwaggerConfiguration {
/**
* 创建Docket类型的对象，并使用spring管理。
* Docket是Swagger中的全局配置对象
*
* @return
*/
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//API帮助文档的描述信息 information
ApiInfo apiInfo = new ApiInfoBuilder()
.contact(//配置swagger文档主体内容
new Contact(
"北京尚学堂 - HHH",//是文档的发布者名称
"http://www.bjsxt.com",//是文档发布者的网站地址，企业网站
"admin@bjsxt.com"))//文档发布者的电子邮箱
.title("Swagger框架学习帮助文档")
.description("Swagger框架学习帮助文档详细描述-Swagger框架是一个用于开发RestAPI帮助文档的框架")
.version("1.1")
.build();
//给docket上下文配置api描述信息
docket.apiInfo(apiInfo);
docket
.select()//获取Docket中的选择器。返回是ApiSelectorBuilder。构建选择器的。如：扫描什么包的注解
.apis(
Predicates.not(//取反。false -> true true -> false
RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解的时候返回true
MyAnnotation4Swagger.class//方法上有什么注解的时候返回true
)
))
.apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller"))//设定扫描哪个包（包含子包）中的注解
.build();//重新构建Docket对象
return docket;
}
}
添加自定义的注解@MyAnnotation4Swagger
在不需要生成接口文档的方法上面添加@MyAnnotation4Swagger注解后，该方法将不会被Swagger进行生成在接口文档中。
@MyAnnotation4Swagger
@RequestMapping("/req")
public String req(String m){
return "req";
}
第二种写法
//第二种写法
docket
.select()//获取Docket中的选择器。返回是ApiSelectorBuilder。构建选择器的。如：扫描什么包的注解
.apis(
Predicates.and(
Predicates.not(//取反。false -> true true -> false
RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解的时候返回true
MyAnnotation4Swagger.class//方法上有什么注解的时候返回true
)
),
RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller")
)
)
//.apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller"))//设定扫描哪个包（包含子包）中的注解
.build();//重新构建Docket对象
return docket;
}
设置范围
通过 public ApiSelectorBuilder paths(Predicate<String> selector) 可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。
下面例子中表示只有以/swagger/**开头的url才能被swagger生成接口文档。
如何希望全部扫描可以使用 paths(PathSelectors.any())
//第一种写法
docket
.select()//获取Docket中的选择器。返回是ApiSelectorBuilder。构建选择器的。如：扫描什么包的注解
.apis(
Predicates.not(//取反。false -> true true -> false
RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解的时候返回true
MyAnnotation4Swagger.class//方法上有什么注解的时候返回true
)
))
.apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller"))//设定扫描哪个包（包含子包）中的注解
.paths(
/* PathSelectors.regex("/swagger/.*")
* 以swagger/开头
* “.”代表任意字符串
* "*“代表0~n个任意字符
* 相当于/swagger/**
*/
PathSelectors.regex("/swagger/.*")//使用正则表达式，约束生成API文档的路径地址
)
.build();//重新构建Docket对象
配置多个规则
//第一种写法
docket
.select()//获取Docket中的选择器。返回是ApiSelectorBuilder。构建选择器的。如：扫描什么包的注解
.apis(
Predicates.not(//取反。false -> true true -> false
RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解的时候返回true
MyAnnotation4Swagger.class//方法上有什么注解的时候返回true
)
))
.apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller"))//设定扫描哪个包（包含子包）中的注解
.paths(
/* PathSelectors.regex("/swagger/.*")
* 以swagger/开头
* “.”代表任意字符串
* "*“代表0~n个任意字符
* 相当于/swagger/**
*/
Predicates.or(//多个规则符合任意一个即可通过
PathSelectors.regex("/swagger/.*"),//使用正则表达式，约束生成API文档的路径地址
PathSelectors.regex("/swagger2/.*"),//使用正则表达式，约束生成API文档的路径地址
PathSelectors.regex("/.x")//使用正则表达式，约束生成API文档的路径地址
)
)
.build();//重新构建Docket对象
Swagger2常用注解
@Api注解
@Api是类上注解。控制整个类生成接口信息的内容。
tags：类的名称。可以有多个值，多个值表示多个副本。
description：描述，已过时。
package com.bjsxt.swagger.controller;
import com.bjsxt.swagger.anno.MyAnnotation4Swagger;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RequestMapping("/swagger")
@RestController
/**
* @Api - 描述当前类型生成帮助文档的信息
* 属性
* - tags : 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制器访问菜单
* - description : 给当前类型生成的帮助文档定义一个描述信息。
*/
@Api(tags = {"MyController","Swagger学习控制器"},description = "测试API类型描述信息")
public class MyController {
@PostMapping("/post")
public String post(){
return "post";
}
@GetMapping("/get")
public String get(String a,String b){
return "get";
}
@MyAnnotation4Swagger
@RequestMapping("/req")
public String req(String m){
return "req";
}
}
tags : 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制，代码中定义了两个，分别为：MyController 和 Swagger学习控制器 。
@ApiOperation
@ApiOperation写在方法上，对方法进行总体描述
- value：接口描述
- notes：提示信息
代码示例：
@ApiOperation(value="接口描述", notes = "接口提示信息")
package com.bjsxt.swagger.controller;
import com.bjsxt.swagger.anno.MyAnnotation4Swagger;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RequestMapping("/swagger")
@RestController
/**
* @Api - 描述当前类型生成帮助文档的信息
* 属性
* - tags : 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制器访问菜单
* - description : 给当前类型生成的帮助文档定义一个描述信息。
*/
@Api(tags = {"MyController","Swagger学习控制器"},description = "测试API类型描述信息")
public class MyController {
@ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求的方法")
@PostMapping("/post")
public String post(){
return "post";
}
@GetMapping("/get")
public String get(String a,String b){
return "get";
}
@MyAnnotation4Swagger
@RequestMapping("/req")
public String req(String m){
return "req";
}
}
@ApiParam
@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。
name：参数名称
value：参数描述
required：是否是必须
代码示例：
public People getPeople(Integer id, @ApiParam(value="姓名",required = true) String name, String address)
案例实操：
package com.bjsxt.swagger.controller;
import com.bjsxt.swagger.anno.MyAnnotation4Swagger;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RequestMapping("/swagger")
@RestController
/**
* @Api - 描述当前类型生成帮助文档的信息
* 属性
* - tags : 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制器访问菜单
* - description : 给当前类型生成的帮助文档定义一个描述信息。
*/
@Api(tags = {"MyController","Swagger学习控制器"},description = "测试API类型描述信息")
public class MyController {
@ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求的方法")
@PostMapping("/post")
public String post(@ApiParam(name="用户名",value="新增用户时提供的用户名",required = true) String a,
@ApiParam(name = "密码",value = "新增用户时提供的密码",required = true) String b){
return "post";
}
@GetMapping("/get")
public String get(String a, String b){
return "get";
}
@MyAnnotation4Swagger
@RequestMapping("/req")
public String req(String m){
return "req";
}
}
@ApiIgnore
@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。和之前讲解的自定义注解@MyAnnotation4Swagger效果类似。只是这个注解是Swagger内置的注解，而@MyAnnotation4Swagger是我们自定义的注解。
案例实操：
//@ApiIgnore - 忽略。当前注解描述的方法或类型，不生成api帮助文档
@ApiIgnore
@GetMapping("/get")
public String get(String a, String b){
return "get";
}
@ApiImplicitParam和@ApiImplicitParams
@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
name：属性名
value：描述
required：是否是必须的
paramType：属性类型
dataType：数据类型
代码示例：
@PostMapping("/getPeople")
@ApiImplicitParam(name = "address",value = "地址",required = true,paramType = "query",dataType = "string")
public People getPeople(Integer id, @ApiParam(value="姓名",required = true) String name, String address){
}
如果希望在方法上配置多个参数时，使用@ApiImplicitParams进行配置。示例如下：
@ApiImplicitParams(value={
@ApiImplicitParam(name="id",value = "编号",required = true),
@ApiImplicitParam(name="name",value = "姓名",required = true)
})
案例实操：
@ApiImplicitParam(name = "m",value = "m参数描述",required = false,paramType = "字符串",dataType = "名值对")
@GetMapping("/test")
public String test(String m,String n){
return "test";
}
@ApiImplicitParams(value = {
@ApiImplicitParam(name="m",value="m参数描述",required = false,paramType = "字符串",dataType = "名值对"),
@ApiImplicitParam(name = "n",value = "n参数描述",required = true,paramType = "字符串String",dataType = "名值对")
})
@GetMapping("/test2")
public String test2(String m,String n){
return "test2";
}
@ApiModel
@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。
- value：名称
- description：描述
代码示例：
@ApiModel(value = "人类",description = "描述")
public class People {}
案例实操：
实体类
package com.bjsxt.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
import java.util.Objects;
/**
* @ApiModel - 描述一个实体类型。
* 这个实体类型如果成为任何一个生成api帮助文档方法的返回值的类型的时候，此注解被解析。
*/
@ApiModel(value = "自定义实体-MyEntity",description = "MyEntity存储用户数据")
public class MyEntity implements Serializable{
private Integer id;
private String name;
private String password;
public MyEntity() {
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
MyEntity myEntity = (MyEntity) o;
return Objects.equals(id, myEntity.id) && Objects.equals(name, myEntity.name) && Objects.equals(password, myEntity.password);
}
@Override
public int hashCode() {
return Objects.hash(id, name, password);
}
}
在MyController中定义方法，返回值为返回MyEntity的一个实例对象
package com.bjsxt.swagger.controller;
import com.bjsxt.swagger.anno.MyAnnotation4Swagger;
import com.bjsxt.swagger.entity.MyEntity;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
@RequestMapping("/swagger")
@RestController
/**
* @Api - 描述当前类型生成帮助文档的信息
* 属性
* - tags : 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制器访问菜单
* - description : 给当前类型生成的帮助文档定义一个描述信息。
*/
@Api(tags = {"MyController","Swagger学习控制器"},description = "测试API类型描述信息")
public class MyController {
@RequestMapping("/testEntity")
public MyEntity testEntity(){
return new MyEntity();
}
@ApiImplicitParams(value = {
@ApiImplicitParam(name="m",value="m参数描述",required = false,paramType = "字符串",dataType = "名值对"),
@ApiImplicitParam(name = "n",value = "n参数描述",required = true,paramType = "字符串String",dataType = "名值对")
})
@GetMapping("/test2")
public String test2(String m,String n){
return "test2";
}
@ApiImplicitParam(name = "m",value = "m参数描述",required = false,paramType = "字符串",dataType = "名值对")
@GetMapping("/test")
public String test(String m,String n){
return "test";
}
@ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求的方法")
@PostMapping("/post")
public String post(@ApiParam(name="用户名（a）",value="新增用户时提供的用户名",required = true) String a,
@ApiParam(name = "密码（b）",value = "新增用户时提供的密码",required = true) String b){
return "post";
}
//@ApiIgnore - 忽略。当前注解描述的方法或类型，不生成api帮助文档
@ApiIgnore
@GetMapping("/get")
public String get(String a, String b){
return "get";
}
@MyAnnotation4Swagger
@RequestMapping("/req")
public String req(String m){
return "req";
}
}
@ApiModelProperty
@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
value：描述
name：重写属性名
required：是否是必须的
example：示例内容
hidden：是否隐藏。
代码示例：
@ApiModelProperty(value = "姓名",name = "name",required = true,example = "张三")
private String name;
实操类型
package com.bjsxt.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
import java.util.Objects;
/**
* @ApiModel - 描述一个实体类型。
* 这个实体类型如果成为任何一个生成api帮助文档方法的返回值的类型的时候，此注解被解析。
*/
@ApiModel(value = "自定义实体-MyEntity",description = "MyEntity存储用户数据")
public class MyEntity implements Serializable{
@ApiModelProperty(value = "主键",name = "主键（id）",required = false,example = "1",hidden = false)
private Integer id;
@ApiModelProperty(value = "姓名",name = "姓名（name）",required = true,example = "张三",hidden = false)
private String name;
@ApiModelProperty(value = "密码",name = "密码（password）",required = true,example = "my-password-123",hidden = false)
private String password;
public MyEntity() {
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
MyEntity myEntity = (MyEntity) o;
return Objects.equals(id, myEntity.id) && Objects.equals(name, myEntity.name) && Objects.equals(password, myEntity.password);
}
@Override
public int hashCode() {
return Objects.hash(id, name, password);
}
}
