springboot项目使用Swagger3

一、Swagger介绍

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

二、Swagger3 准备工作

1、在pom.xml导入依赖

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-boot-starterartifactId>
            <version>3.0.0version>
        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/**"

springboot项目使用Swagger3_第1张图片
我们可以通过配置类修改接口文档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();
    }

}

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

springboot项目使用Swagger3_第2张图片

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属性上

你可能感兴趣的:(java,Spring,Boot,Swagger3,spring,boot,后端,java)