当前位置 博文首页 > RtxTitanV的博客:SpringBoot2.x 集成 Swagger2
Swagger是一款RESTFUL接口的文档在线自动生成加功能测试的软件,提供描述、生产、消费和可视化RESTful Web Service。Swagger也是一个api文档维护组织,后来成为了OpenAPI(一个业界的api文档标准)标准的主要定义者,现在最新的版本为17年发布的Swagger3(OpenAPI3)。本文所用的Swagger2基于OpenAPI2,于2017年停止维护。
SpringFox是Spring社区维护的一个项目(非官方),帮助使用者将Swagger2集成到Spring中。常用于Spring中帮助开发者生成文档,并可以轻松的在SpringBoot中使用,目前已经支持OpenAPI3标准。本文通过引入SpringFox来使用Swagger2。
本文主要对SpringBoot2.x集成Swagger2进行简单总结,其中SpringBoot使用的2.4.5
版本。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.10.5</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.10.5</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-spring-webmvc</artifactId>
<version>2.10.5</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<!-- lombok插件 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.8</version>
</dependency>
package com.rtxtitanv.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.ArrayList;
import java.util.List;
/**
* @author rtxtitanv
* @version 1.0.0
* @name com.rtxtitanv.config.Swagger2Config
* @description Swagger2配置类
* @date 2021/6/6 15:16
*/
@Configuration
@EnableKnife4j
@EnableSwagger2WebMvc
public class Swagger2Config {
/**
* 配置默认分组
*
* @return springfox.documentation.spring.web.plugins.Docket
*/
@Bean
public Docket defaultApi() {
// DocumentationType.SWAGGER_2为Swagger2的文档类型
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
/*
* 通过apis和paths方法设置ApiSelector的构建规则
* ApiSelectorBuilder apis(Predicate<RequestHandler> selector)
* RequestHandlerSelectors.any():构建所有API
* RequestHandlerSelectors.none():所有API都不构建
* RequestHandlerSelectors.basePackage():构建指定包路径下的所有API
* RequestHandlerSelectors.withClassAnnotation():仅构建带有指定类注解的API
* RequestHandlerSelectors.withMethodAnnotation():仅构建带有指定方法注解的API
* ApiSelectorBuilder paths(Predicate<String> selector)
* PathSelectors.any():构建所有请求路径的API
* PathSelectors.none():所有请求路径的API都不构建
* PathSelectors.regex():仅构建正则匹配的请求路径的API
* PathSelectors.ant():仅构建与ant模式匹配的API
*/
.apis(RequestHandlerSelectors.basePackage("com.rtxtitanv.controller.other")).paths(PathSelectors.any())
.build();
}
/**
* 配置user分组
*
* @return springfox.documentation.spring.web.plugins.Docket
*/
@Bean
public Docket userApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.rtxtitanv.controller.user"))
// groupName方法设置分组名称,globalOperationParameters方法添加全局参数
.paths(PathSelectors.regex("/user/.*")).build().groupName("user").globalOperationParameters(token())
.ignoredParameterTypes(HttpServletRequest.class, HttpServletResponse.class);
}
/**
* 配置order分组
*
* @return springfox.documentation.spring.web.plugins.Docket
*/
@Bean
public Docket orderApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.rtxtitanv.controller.order"))
.paths(PathSelectors.regex("/order/.*")).build().groupName("order").globalOperationParameters(token())
.ignoredParameterTypes(HttpServletRequest.class, HttpServletResponse.class);
}
/**
* 构建API文档基本信息
*
* @return springfox.documentation.service.ApiInfo
*/
private ApiInfo apiInfo() {
// 联系人信息:分别为作者、主页、邮箱
Contact contact = new Contact("RtxTitanV", "https://blog.csdn.net/RtxTitanV", "RtxTitanV@xxx.com");
// 构建API文档的基本信息:依次为API标题、API描述、API联系人信息、API版本、API许可、API许可Url
return new ApiInfoBuilder(