【Java】【组件使用】【Swagger2的基本使用】
以下使用皆基于springboot项目。
一、Jar包的引入的两种方式
1.1、使用swagger官方提供的jar包
1.1.1、第一步在pom文件里引入2.9.2版本的jar包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
注：springboot从2.6.0版本开始不支持2.9.2版本的jar包，低于此版本的才可以引入此jar包
1.1.2、第二步 添加配置文件
1.1.3、第三步 添加注解
在起始类添加注解@EnableSwagger2：
或者在Swagger配置文件添加注解@EnableSwagger2：
注：任意一个即可，但不能不写
1.2、使用非官方封装的包（-）
这个和官方的swagger2的区别就在于，自动化配置，引入jar包和添加注解即可使用，当然，如果需要个性化操作，就需要自己在yml文件添加配置。
1.2.1、第一步 jar包引入
<!-- https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.1.RELEASE</version>
</dependency>
1.2.2、第二步 增加注解@EnableSwagger2Doc
1.2.3、可选配置
yml格式配置：
1.2.4、界面
和原生swagger界面并无区别
1.3、使用非官方封装的包（二）
和上面一个很相似，不过在这基础上，又参考了swagger-bootstrap-ui
注：1.X 版本需要在启动类添加 `@EnableSwagger2Doc` 但是 2.X 版本后无需添加
https://gitee.com/battcn/spring-boot-starter-swagger/
<dependency>
<groupId>com.battcn</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>2.1.5-RELEASE</version>
</dependency>
二、增强版-可视化界面（支持文档导出）
http://${host}:${port}/doc.html
2.1、老版的使用
2.1.1、jar包的引用
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
2.1.2、在配置文件或者启动类添加注解@EnableSwaggerBootstrapUI
2.1.3、界面
2.2、新版的使用
2.2.1、jar包的引用
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
2.2.2、界面
2.3、如果被拦截器拦截的处理方式
首先，swagger配置文件实现WebMvcConfigurer
然后重写addResourceHandlers方法，并添加:
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
示例:
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
}
三、使用注意点
3.1、项目进行了反向代理时的处理
配置反射路径时并没有将context-path的路径映射，就需要这里代码：
四、注解的使用
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数
五、Swagger配置文件示例
package com.jh.plug.config;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.paths.RelativePathProvider;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import javax.servlet.ServletContext;
import java.util.Collections;
import java.util.HashSet;
import java.util.Set;
@EnableSwagger2
@Configuration
//Profile是方法1（只在dev和test环境下开启）
//@Profile({"dev","test"})
public class SwaggerConfig implements WebMvcConfigurer {
@Bean("shopApi")
public Docket createRestApi(ServletContext servletContext) {
return new Docket(DocumentationType.SWAGGER_2)
// .pathProvider(new RelativePathProvider(servletContext) {
// @Override
// public String getApplicationBasePath() {
// return "/jherp-shop-api";
// }
// })
.groupName("shop")// 不能为中文，否则termsOfServiceUrl打不开
.consumes(DEFAULT_PRODUCES_AND_CONSUMES)
.produces(DEFAULT_PRODUCES_AND_CONSUMES)
.useDefaultResponseMessages(false)//不使用默认相应code
.apiInfo(apiInfo())// 用于生成API信息
.select()
.apis(RequestHandlerSelectors.basePackage("com.jh.plug"))// 用于指定扫描哪个包下的接口
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//为有@Api注解的Controller生成API文档
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
//创建
.build();
}
/**
* 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("鲸汇平台对接项目API") // 可以用来自定义API的主标题
.description("<p>鲸汇平台对接项目SwaggerAPI管理，主要用于测试平台接口连通性。</p>") // 可以用来描述整体的API
.termsOfServiceUrl("") // 用于定义服务的域名
.version("1.0") // 可以用来定义版本。
.build(); //
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
}
//配置content type
private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES =
new HashSet<>(Collections.singletonList("application/json"));//,"application/xml"，只需要json格式
@Bean
public UiConfiguration uiConfiguration() {
return UiConfigurationBuilder.builder()
// 隐藏UI上的Models模块：-1为不显示，默认为0显示
.defaultModelsExpandDepth(0)
.build();
}
}