Swagger简介:
号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
直接运行，在线测试API
支持多种语言 （如：Java，PHP等）
官网：https://swagger.io/
SpringBoot集成Swagger:
添加Maven依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
编写HelloController:
要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面:
注意在Controller的方法请求路径映射不要使用@RequestMapping来配置，应该直接使用具体请求方法的注解，如@GetMapping、@PostMapping等。因为使用@RequestMapping配置在API文档上一个方法默认会生成七种请求的API文档信息，如下图所示:
配置Swagger:
Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。:
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
可以通过apiInfo()属性配置文档信息:
//配置了swagger信息=apiinfo
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("本体","https://blog.csdn.net/shiqinghuan","1874234461@qq.com");
return new ApiInfo(
"人间有味是清欢", //标题
"描述信息", //描述
"v1.0", //版本
"团队的服务url", //服务条款的url
contact, //作者信息
"Apache 2.0", //版本许可
"http://www.apache.org/licenses/LICENSE-2.0", //版本许可url
new ArrayList()
);
}
Docket 实例关联上 apiInfo():
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
重启项目，访问测试 http://localhost:8080/swagger-ui.html：
配置扫描接口：
构建Docket时通过select()方法配置怎么扫描接口。
//RequestHandlerSelectors配置要扫描接口的方式
//属性：
//basePackage：指定要扫描的包
//any:扫描全部
//none:什么都不扫描
//withMethodAnnotation:扫描方法上的注解
//.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
//withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
//.apis(RequestHandlerSelectors.withClassAnnotation(PostMapping.class))
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.benti.swagger"))
//设置扫描指定包下的类
.build();/工厂模式
}
还可以配置接口扫描过滤：：
//.paths(PathSelectors.ant("/benti/**")) //配置接口扫描过滤：
//ant(String antPattern)：只扫描指定的路径下的请求。
//any()：任何请求都会被扫描。
//none()：不扫描请求。
//regex(String pathRegex)：通过正则表达式来匹配请求。
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.benti.swagger"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
配置Swagger开关：
通过enable()方法配置是否启用swagger，
如果是false，swagger将不能在浏览器中访问了
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
//配置是否启用Swagger，如果是false，在浏览器将无法访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.benti.swagger"))
.build();
}
动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示：
//配置了swagger 的docket的bean的实例
@Bean
public Docket docket(Environment environment) {
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("本体")
.enable(flag) //是否启动swagger 如果为flase，则swagger不能在浏览器中访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.benti.swagger.controller"))
.build()//工厂模式
;
}
可以在项目中增加一个dev的配置文件查看效果！
application-dev.properties：
server.port=8080
application.properties：
#设置要激活的环境
spring.profiles.active=dev
配置API分组：
’
如果没有配置分组，默认是default。
通过groupName()方法即可配置分组：
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("本体") // 配置分组
// 省略其他配置....
}
配置多个分组只需要配置多个docket即可：
//配置多个分组，多个docket实例即可
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("清欢");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("渡口");
}
显示：
实体配置：
新建一个实体类，类上使用@ApiModel注解来添加该实体类的描述信息，此注解其实就是注释，只不过它会被Swagger识别。
pojo.User:
//和注释差不多，但是会被swagger识别
@ApiModel("用户实体") //实体类的描述信息
public class User {//只有在controller中返回值用到,这个类才会显示在swagger中
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
请求的接口配置，如果要在swagger-ui.html中看到实体类的配置，那么这个实体类一定是在请求的返回值或者泛型中，只有这样它才会被映射。
//只有返回值用到才会显示
@GetMapping("/getUser")
public User getUser(){
return new User();
}
在类上使用@Api注解来添加类的描述信息，
在方法上使用@ApiOperation注解来添加方法的描述信息，
在方法的形参上使用@ApiParam注解来添加参数的描述信息。
HelloController:
@RestController
@Api(tags = "这是一个控制类1")
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "hello";
}
@ApiOperation("hello 方法2")
@GetMapping("/hello2")
public String hello2(@ApiParam("用户名？") String username) {
return "hello"+username;
}
//只要我们的接口中，返回值存在实体类，他就会被扫描到swagger
@PostMapping("/user")
public User user() {
return new User();
}
}
总结：
//conroller类的描述
@Api(tags = "描述")
//controller方法的注释
@ApiOperation("哟哟哟")
//实体类的注释
@ApiModel("shiro实体类")
//实体类属性的注释
@ApiModelProperty("这是ID")
//controller方法参数的注释
@Api(tags = "")
Swagger接口文档的皮肤包（扩展）：
1、默认的皮肤包： http://localhost:8080/swagger-ui.html：
<!-- 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>
bootstrap-ui： http://localhost:8080/doc.html:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
ui-layer：http://localhost:8080/docs.html:
<!-- https://mvnrepository.com/artifact/com.github.caspar-chen/swagger-ui-layer - ->
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>
mg-ui： http://localhost:8080/document.html:
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
