springboot项目使用Swagger3

一、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 {

    @Bean
    public 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属性上