一、Swagger介绍

• 号称世界上最流行的Api框架；
• Restful Api 文档在线自动生成工具=>Api文档与API定义同步更新
• 直接运行，可以在在线测试API 接口
• 支持多种语言：（java，Php…）

二、Swagger3 准备工作

1、在pom.xml导入依赖

<!--        Swagger3--><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency>

注：导入依赖运行报错，可在配置中添加

spring:mvc:pathmatch:matching-strategy: ant_path_matcher

2、配置类

访问地址：

文档接口地址：http://localhost:9990/v3/api-docs
文档页面地址：http://localhost:9990/swagger-ui/index.html

注意：需要在配置上需要释放Swagger被拦截器拦截的路径，如

"/swagger-resources/**"
,"/webjars/**"
,"/swagger-ui/**"
,"/v3/**"
,"/swagger-ui.html/**"

我们可以通过配置类修改接口文档UI的内容：

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/**
* Swagger3配置类
* */
@Configuration
@EnableOpenApi
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()/**加了@ApiOperation注解的类，才生成接口文档*/.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))/**显示所有路径*/.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("XX接口文档").description("XX接口文档XXXX").version("1.0").build();}}

修改之后接口文档的页面：

3、Swagger的基本使用

swagger 2	OpenAPI 3	注解位置
@Api(tags = “接口类描述”)	@Tag(name = “接口类描述”)	Controller 类上
@ApiOperation	@Operation(summary =“接口方法描述”)	Controller 方法上
@ApiImplicitParams	@Parameters	Controller 方法上
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法上 @Parameters 里
@ApiParam	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel	@Schema	DTO类上
@ApiModelProperty	@Schema	DTO属性上