spring boot集成swagger2（接口注释说明文档）
目录
一、swagger2介绍
二、spring boot集成swagger2使用
1. 添加入Swagger2的依赖
2.Swagger2Config（Swagger2配置）
3.PagerIDto（分页）
4. 启动应用程序并访问swagger-ui.html
三、为swagger-ui增加密码
1.pom.xml添加依赖
2.application.yml添加配置
3.WebSecurityConfigurerAdapter（拦截器）
4.重启项目再次访问swagger-ui
四、常用注解
一、swagger2介绍
swagger2是一个能用过注解的形式帮助我们生产api开发文档的工具包，同时也能够方便我们对api的一个实时管理和方便对api接口的调试，对于调用者也能更加直观发现问题，在api对接的过程中能提高我们对接时的效率。
效果图
二、spring boot集成swagger2使用
1. 添加入Swagger2的依赖
io.springfox
springfox-swagger2
2.8.0
io.springfox
springfox-swagger-ui
2.8.0
2.Swagger2Config（Swagger2配置）
package com.example.swagger2demo.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;
/**
* @Auther: yaohongan
* @Date: 2019/10/4 20:14
* @Description:Swagger2配置
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("demo")
.apiInfo(apiInfo())
.select()
// 设置basePackage会将包下的所有类的所有方法作为api
// .apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
// 只有标记@ApiOperation才会暴露出给swagger
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.regex("/api/.*"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API接口文档")
.description("RESTful风格接口")
.termsOfServiceUrl("https://blog.csdn.net/vbirdbest") // 服务条款网址
.version("1.0")
.contact(new Contact("mengday", "httphttp://wwww.xxx.com", "[email protected]"))
.build();
}
}
3.PagerIDto（分页）
package com.example.swagger2demo.dto;
/**
* @Auther: yaohongan
* @Date: 2019/10/4 20:25
* @Description:分页相关
*/
import io.swagger.annotations.ApiModelProperty;
public class PagerIDto {
@ApiModelProperty(value = "页码", required = true)
private int page;
@ApiModelProperty(value = "每页条数", required = true)
private int size;
public PagerIDto() {
}
public int getPage() {
return page;
}
public void setPage(int page) {
this.page = page;
}
public int getSize() {
return size;
}
public void setSize(int size) {
this.size = size;
}
}
4. 启动应用程序并访问swagger-ui.html
http://localhost:8080/swagger2demo/swagger-ui.html#/
三、为swagger-ui增加密码
1.pom.xml添加依赖
org.springframework.boot
spring-boot-starter-security
2.application.yml添加配置
spring:
security:
basic:
path: /swagger-ui.html
enabled: true
user:
name: admin
password: 123456
3.WebSecurityConfigurerAdapter（拦截器）
package com.example.swagger2demo.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.WebSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
/**
* Spring Security 会拦截swagger-ui.html 同样也会拦截api，这里将或略掉/api/下的所有子路径
*/
@EnableWebSecurity
@Configuration
class CustomWebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {
@Override
public void configure(WebSecurity web) throws Exception {
super.configure(web);
web.ignoring().antMatchers("/api/v1/**");
}
}
4.重启项目再次访问swagger-ui
访问 http://localhost:8080/swagger2demo/swagger-ui.html 会跳转到http://localhost:8080/swagger2demo/login 输入application.yml配置的用户名密码即可跳转到到swagger-ui.html
四、常用注解
@Api(description = “接口类的描述”)
@ApiOperation(value = “接口方法的名称”, notes = “备注说明”)
@ApiParam(name = “参数名称”, value = “备注说明”, required = 是否必须)：标注在方法的参数上 用于描述参数的名称、备注、是否必须等信息
@ApiImplicitParam(paramType = “query”, name = “password”, dataType = “String”, required = true, value = “密码”, defaultValue = “123456”)用于描述方法的参数，标注在方法上，和@ApiParam功能一样，只是标注的位置不同而已
paramType：参数类型，即参数放在哪个地方
header–>请求参数的获取：@RequestHeader，参数放在请求头
query–>请求参数的获取：@RequestParam，参数追加在url后面
path（用于restful接口）–>请求参数的获取：@PathVariable
body 使用@RequestBody接收数据 POST有效，参数放在请求体中
form
name：参数名
allowMultiple = true, 参数为数组List集合使用, 比如List< Order>: allowMultiple = true,
dataType=“Order”
dataType：参数的数据类型
required：参数是否必须传
value：参数的描述
defaultValue：参数的默认值
@ApiImplicitParams： 用于包含多个@ApiImplicitParam
@ApiResponse(code = 0, message = “success”),
code：响应码，例如400
message：信息，一般是对code的描述
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
value 参数名称
required 是否必须 boolean
hidden 是否隐藏 boolean
@ApiIgnore：用于或略该接口，不生成该接口的文档
apis(RequestHandlerSelectors.basePackage(“com.example.demo2.controller”)) 会将包下的所有Controller类带有@RequestMapping或者XxxMapping都会给暴露给swagger，如果想部分类暴露出去部分不暴露出去，只能将不暴露的controller放到其他package中，放在同一个package是做不到的。
apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)): 只有在类上使用@Api注解标注并且在方法上使用@ApiOperation注解才会暴露给swagger，这种方式没有包名的限制，可以将需要暴露的接口分散到各个包里，只要类上有@Api注解方法上有@ApiOperation注解就能暴露出来，如果不想暴露出来就不用使用这两个注解。
参考文档：https://blog.csdn.net/vbirdbest/article/details/79680732