本文由 简悦 SimpRead 转码， 原文地址 blog.csdn.net
前言
随着微服务架构的普及和 API 数量的增长，API 文档的管理和维护变得尤为重要。Swagger 作为一款强大的 API 文档生成工具，能够帮助我们自动生成 API 文档，并提供在线测试功能，极大地提高了开发效率。本文将介绍如何在 Spring Boot 项目中集成 Swagger 3.0，实现 API 文档的自动化生成。
一、swagger 3 的使用
Open API
OpenApi 是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被 linux 列为 api 标准，从而成为行业标准。
Swagger
swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为 17 年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的 swagger2（17 年停止维护并更名为 swagger3）swagger2 的包名为 io.swagger，而 swagger3 的包名为 io.swagger.core.v3。
SpringFox
SpringFox 是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在 spring boot 中使用。目前已经支持 OpenAPI3 标准。
升级到 OpenAPI3（java 中 swagger1.x 对应 OpenAPI2、swagger 2.x 对应 OpenAPI3）官方文档
3.0 相关特性
支持 Spring 5，Webflux（仅请求映射支持，尚不支持功能端点）、Spring Integration
补充官方在 spring boot 的自动装配 pringfox-boot-starter 以后可以直接依赖一个 dependency
与 2.0 更好的规范兼容性
支持 OpenApi 3.0.3
轻依赖 spring-plugin，swagger-core
现有的 swagger2 批注将继续有效并丰富开放式 API 3.0 规范
常用注解说明
@Api：用在请求的类上，表示对类的说明
tags: 说明该类的作用，可以在UI界面上看到的注解
value: 该参数没什么意义，在UI界面上也看到，所以不需要配置
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value: 说明方法的用途、作用
notes: 方法的备注说明
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息，一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
name：属性名
value：属性的汉字说明、解释
@ApiParam 用于 Controller 中方法的参数说明，放在方法签名当中
value：参数说明
required：是否必填
@ApiIgnore：使用该注解忽略这个API
二、在项目中的使用
1、引入 pom 包，这里同时引入增强包 knife4j
<!-- Swagger3 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
2、application.yml 添加配置
############## Swagger配置 ##############
swagger:
basic:
enable: true
username: swagapi-api
password: dz@111222
# 是否开启swagger
enabled: true
3. 添加自定义配置类 SwaggerConfig ：
/**
* Swagger2的接口配置
*
* @author dz
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
/**
* 是否开启swagger
*/
@Value("${swagger.enabled}")
private boolean enabled;
/**
* 创建API
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(enabled)
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//扫描所有
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
/* 设置安全模式，swagger可以设置访问token */
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
/**
* 支持的通讯协议集合
*
* @param type1
* @param type2
* @return
*/
private Set<String> newHashSet(String type1, String type2) {
Set<String> set = new HashSet<>();
set.add(type1);
set.add(type2);
return set;
}
/**
* 安全模式，这里指定token通过Authorization头请求头传递
*/
private List<ApiKey> securitySchemesOld() {
List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
/**
* 认证的安全上下文
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> securitySchemes = new ArrayList<>();
securitySchemes.add(new ApiKey("token", "token", "header"));
return securitySchemes;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("接口文档")
// 版本
.version("版本号:V1.0")
.build();
}
}
4. 添加拦截器配置 WebConfig，放行相关目录
/**
* WebConfig 配置类
*/
@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//配置 swagger 静态页面
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
5.Spring Security 中 拦截器放行
/**
* Spring Security 配置类
* EnableWebSecurity debug = true 开启调试，正式环境要关闭
*/
@Configuration
@EnableWebSecurity(debug = true)
public class WebSecurityConfig {
/**
* 授权
* @param http
* @return
* @throws Exception
*/
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
//链式编程
// 首页所有人都可以访问，功能也只有对应有权限的人才能访问到
// 请求授权的规则
http.csrf().disable()
.authorizeRequests()
//swagger 特定权限访问页允许访问
.antMatchers("/swagger*/**","/webjars/**","/*/api-docs").permitAll()
.antMatchers("/druid/**").anonymous()
.antMatchers("/css/**", "/js/**", "/img/**","/**/doc.html").permitAll()
.anyRequest().authenticated()；
return http.build();
}
}
6. 启动类 添加 @EnableSwagger2 注解
@SpringBootApplication
@Slf4j
@EnableSwagger2
@MapperScan(basePackages = {"com.dz.springsecuritydemo.mapper"})
public class SpringsecuritydemoApplication {
public static void main(String[] args) throws UnknownHostException {
ConfigurableApplicationContext application = SpringApplication.run(SpringsecuritydemoApplication.class, args);
Environment env = application.getEnvironment();
log.info("\n-------------------------------------------------------------------------\n\t" +
"应用启动成功! 访问连接:\n\t" +
"Swagger文档: \t\thttp://{}:{}{}/doc.html\n\t" +
"-------------------------------------------------------------------------",
InetAddress.getLocalHost().getHostAddress(),
env.getProperty("server.port"),
env.getProperty("server.servlet.context-path")
);
}
}
7. 启动项目，访问 swagger 文档
http://localhost:8080/spring-security-demo/doc.html