SpringBoot集成Swagger
文章目录
简介:
前后端分离:
- 前端 ->前端控制层,视图
- 后端 ->后端控制层,服务层,数据访问层
- 前后端通过API进行交互
- 前后端相对独立且松耦合
产生的问题:
- 前后端集成,前端或者后端无法左到"“及时协商,今早解决”",最终问题集中爆发
Swagger
- 号称世界最流行的API的框架
Restful Api
文档在线自动生成器,-----> API文档与API定义同步更新- 直接运行,在线测试API
- 支持多种语言(JAVA,PHP)
- 官网:https://swagger.io/
SpringBoot集成Swagger
SpringBoot集成Swagger==>springfox, 两个jar包
- SpringFox-swagger2
- swagger-springmvc
使用Swagger
要求:jdk 1.8 + 否则swagger2无法运行
步骤:
1、新建一个SpringBoot-web项目
2、添加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>
3、编写HelloController,测试确保运行成功!
4、要使用Swagger,我们需要编写一个配置类-SwaggerConfig来配置 Swagger
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
5、访问测试 :http://localhost:8080/swagger-ui.html
配置Swagger
-
Swagger实例Bean是Docket,所以通过Dacket实例来配置Swagger
-
可以通过apiInfo()配置属性文档信息
-
Docket 实例关联上 apiInfo()
-
重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果;
@Configuration//配置类
@EnableSwagger2 //开启Swagger2的配置
public class SwaggerConfig {
@Bean //配置docket以配置Swagger具体参数
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(apilnfo())
.enable(flag)
.select()
//RequestHandlerSelectors 配置要扫描的接口方式
//basePackage: 指定要扫描的包
// any() 扫描全部
//none() 不扫描
//withClassAnnotation() 扫描类上的注解
//withMethodAnnotation() 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.nie.controller"))
//过滤
//.paths(PathSelectors.ant(""))
.build();
}
//配置文档信息
private ApiInfo apilnfo() {
Contact contact = new Contact("聂大钊", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfo(
"大钊Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://XXX/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}
}
配置扫描接口
-
构建Docket时通过select()方法配置怎么扫描接口
return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apilnfo()) .enable(flag) .select() //RequestHandlerSelectors 配置要扫描的接口方式 //basePackage: 指定要扫描的包 // any() 扫描全部 //none() 不扫描 //withClassAnnotation() 扫描类上的注解 //withMethodAnnotation() 扫描方法上的注解 .apis(RequestHandlerSelectors.basePackage("com.nie.controller")) // 配置如何通过path过滤,即这里只扫描请求以`/nie`开头的接口 //.paths(PathSelectors.ant("/nie/**")) .build();
-
可以通过配置其他方式扫描接口,这里注释一下所有的配置方式:
any() // 扫描所有,项目中的所有接口都会被扫描到 none() // 不扫描接口 // 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求 withMethodAnnotation(final Class<? extends Annotation> annotation) // 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口 withClassAnnotation(final Class<? extends Annotation> annotation) basePackage(final String basePackage) // 根据包路径扫描接口
-
接口扫描过滤
@Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口 .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")) // 配置如何通过path过滤,即这里只扫描请求以/nie开头的接口 .paths(PathSelectors.ant("/nie/**")) .build(); }
配置Swagger开关
-
通过enable()方法配置是否启用Swagger,如果是false,swagger将不能在浏览器中访问了
.enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
-
如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
@Bean //配置docket以配置Swagger具体参数 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(apilnfo()) .enable(flag) .select() //RequestHandlerSelectors 配置要扫描的接口方式 //basePackage: 指定要扫描的包 // any() 扫描全部 //none() 不扫描 //withClassAnnotation() 扫描类上的注解 //withMethodAnnotation() 扫描方法上的注解 .apis(RequestHandlerSelectors.basePackage("com.nie.controller")) //过滤 //.paths(PathSelectors.ant("")) .build(); }
配置API分组
1、如果没有配置分组,默认是default。通过groupName()方法即可配置分组:
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分组
// 省略配置....
}
2、重启项目查看分组
3、如何配置多个分组?配置多个分组只需要配置多个docket即可:
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("groupA");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("groupB");
}
@Bean //配置docket以配置Swagger具体参数
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)
.groupName("大钊")
.apiInfo(apilnfo())
.enable(flag)
.select()
//RequestHandlerSelectors 配置要扫描的接口方式
//basePackage: 指定要扫描的包
// any() 扫描全部
//none() 不扫描
//withClassAnnotation() 扫描类上的注解
//withMethodAnnotation() 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.nie.controller"))
//过滤
//.paths(PathSelectors.ant(""))
.build();
}
实体配置
1、新建一个实体类
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
-
只要这个实体在请求接口的返回值上(即使死泛型),都能映射到实体项中
@RequestMapping("/getUser") public User getUser(){ return new User(); }
@ApiModel
注解让实体显示在这里.而是只要出现接口方法的返回值上的实体都会显示,而@ApiModel
和@ApiModelProperty
这两个注解只是为实体添加注释的。
@ApiModel
为类添加注释
@ApiModelProperty
为类属性添加注释
常用注解
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上 |
总结
- 通过Swagger给一些比较难理解的属性或者接口,增加注释信息
- 接口文档实时更新
- 可以在线测试