Swagger 的介绍以及使用
本文代码已经同步到码云 ,欢迎大家 star https://gitee.com/njitzyd/JavaDemoCollection
Swagger 简介
Swagger 是一个主要用来在线生成文档的插件,这里主要用来动态生成api接口供前后端进行交互,如果不生成的话就需要写静态文档来交互,那样不仅很慢而且不容易修改,那Swagger就可以解决这个问题。
新建一个SpringBoot 项目,只加入 web 的启动器,然后添加下面两个依赖:
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
@RestController
public class DemoController {
/**
*
* @description: 注意这种写法Swagger 会生成很多个接口(虽然参数里指定了GET,Swagger扫描不到)
* 所以在实际的开发中尽量使用 @GetMapping 等这种指定了方法的方式
* @param: []
* @return: java.lang.String
* @date: 2020/8/2
*/
@RequestMapping(value = "index",method = RequestMethod.GET)
public String hello(){
return "helloWorld";
}
}
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
访问地址:http://localhost:8080/swagger-ui.html,可以看到Swagger 的页面:
刚刚启动后,页面的内容都是默认的,在实际使用中需要我们进行配置。
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
.build();
}
其中RequestHandlerSelectors 有很多可以配置的方法,具体如下,可以根据自己的项目选择:
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) // 根据包路径扫描接口
除此之外,我们还可以通过.paths
配置接口扫描过滤:
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/njit/**"))
.build();
}
PathSelectors 也是可以多种配置的:
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/njit开头的接口
.paths(PathSelectors.ant("/njit/**"))
.build();
}
动态配置当项目处于test、dev环境时显示swagger,否则不显示
首先在application.properties 中配置激活的配合环境,然后再做如下配置:
@Bean
public Docket docket(Environment environment) {
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean flag = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/njit开头的接口
//.paths(PathSelectors.ant("/njit/**"))
.build();
}
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfoBuilder()
.title("自定义标题")
.description("自定义描述")
.contact(contact)
.version("1.0.0-RELEASE")
.build();
}
很简单只要配置groupName()即可,如果想要配置多个分组,name就配多个Docket实例,注意实例的名称不能重复。
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分组
// 省略配置....
}
配置多个分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
// @ApiModel为类添加注释
// @ApiModelProperty为类属性添加注释
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
这样就可以在controller类以及方法以及参数中使用相应的注解来完善我们的Swagger,特别说明的是,在生产环境中一定要关闭Swagger,一方面提高性能,更重要的是安全问题,会把自己的接口暴露出去!!!