Spring Boot 整合 Swagger
Swagger
简介
- 用于前后端联调,后端自动生成接口文档,前后端可以部署在不同的服务器上,所以为了保证实时性,后端接口一设计就会实时的生成接口文档,前后端相互独立,通过API交互。
- RestFul Api 文档在线自动生成工具=>
Api文档与Api定义同步更新
。 - 直接运行,可以在线测试api
- 支持多种语言
- 官网:https://swagger.io/
- 访问:http://localhost:8080/swagger-ui.html
使用
- 依赖导入swagger2和swagger-ui
<!--swagger2-->
<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>
- swaggerConfig
package com.qiumin.springbootshiro.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
@EnableSwagger2
public class swaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(getApiInfo())
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.qiumin.springbootshiro.controller"))
.build();
}
private ApiInfo getApiInfo(){
Contact contact = new Contact("邱敏", "https://blog.kuangstudy.com/", "2784618689@qq.com");
return new ApiInfo("邱敏的SwaggerAPI文档",
"自律也是一门学问",
"v1.0",
"https://blog.kuangstudy.com/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
- 配置一个Docket和一个ApiInfo方法用于Docket。
- 为了解决由于springboot版本过高的问题,需在springboot的配置文件加上spring.mvc.pathmatch.matching-strategy=ant_path_matcher
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
21.1 根据环境判断是否开启swagger
package com.qiumin.springbootshiro.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
@EnableSwagger2 //开启swagger2
public class swaggerConfig {
@Bean
public Docket docket(Environment environment){
//根据环境判断是否开启swagger
Profiles profiles=Profiles.of("dev","test"); //dev test环境下开启
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(getApiInfo())
.enable(flag) //dev test环境下开启
.select()
.apis(RequestHandlerSelectors.basePackage("com.qiumin.springbootshiro.controller"))
.build();
}
private ApiInfo getApiInfo(){
Contact contact = new Contact("邱敏", "https://blog.kuangstudy.com/", "2784618689@qq.com");
return new ApiInfo("邱敏的SwaggerAPI文档",
"自律也是一门学问",
"v1.0",
"https://blog.kuangstudy.com/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
21.2 分组及接口注释
分组
- 每一个
Docket
就是一个组,下面就表示为有三个组,分组可以协作开发,每个人将自己的接口放在自己的组中。
@Bean
public Docket docket2(){ //一组
return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin1").apiInfo(getApiInfo());
}
@Bean
public Docket docket3(){ //一组
return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin2").apiInfo(getApiInfo());
}
@Bean
public Docket docket4(){ //一组
return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin3").apiInfo(getApiInfo());
}
接口注释:我们可以用注解对接口进行解释说明
- 实体类的注解即实体类中字段的解释@ApiModel,@ApiModelProperty,标上了这两个注解在那个swagger页面就会有对应的解释说明
@Data
@AllArgsConstructor
@NoArgsConstructor
//注释
@ApiModel("用户类")
public class userPojo {
@ApiModelProperty("用户id")
private Integer id;
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("密码")
private String password;
@ApiModelProperty("用户权限")
private String perms;
}
- 配置一个访问接口
@RequestMapping("/user")
@ResponseBody
public userPojo getuserPojo(){
return new userPojo();
}
- 接口注释 @ApiOperation(“自定义”)
@ApiOperation("登出请求")
@RequestMapping("/loginOut")
private String loginOut(){
Subject subject = SecurityUtils.getSubject();
subject.logout();
return "index";
}
- 参数注释 @ApiParam
@RequestMapping("/loginOut")
private String loginOut(@ApiParam("用户名") String username){
Subject subject = SecurityUtils.getSubject();
subject.logout();
return "index";
}
21.3 swagger总结
-
可以通过swagger给一些比较难理解的属性或者接口,增加注释信息
-
接口文档实时更新
-
在swagger页面可以进行测试,通过接口向后端请求数据
-
可在线测试 【try it】
-
注意点:项目正式发布的时候应将swagger关闭,防止将接口暴露给外界,造成信息安全隐患,而且可以节省运行内存。
return “index”;
}
### 21.3 swagger总结
1. 可以通过swagger给一些比较难理解的属性或者接口,增加注释信息
2. 接口文档实时更新
3. 在swagger页面可以进行测试,通过接口向后端请求数据
4. 可在线测试 【try it】
5. **==注意点:项目正式发布的时候应将swagger关闭,防止将接口暴露给外界,造成信息安全隐患,而且可以节省运行内存。==**
**qiumin**