Swagger2与Swagger3的演进关系（区别）

 

一、引入

swagger2需要引入2个jar包，swagger3只需要一个

swagger2 引用两个包

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

 swagger3引入一个jar

          
                
                        io.springfox
                        springfox-boot-starter
                        3.0.0
                
 

二、配置（yml和java）

swagger2 java配置

package demo.config;
 
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.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
import java.util.ArrayList;
import java.util.List;
 
/**
 * Swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("demo.controller")).paths(PathSelectors.any())
                .build().globalOperationParameters(setHeaderToken());
 
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XXX 项目接口文挡")
                .description("swagger实战")  //说明信息
                .termsOfServiceUrl("") //文档生成的主页地址
                .version("1.0").build(); //文档版本
    }
 
    private List setHeaderToken() {
        List pars = new ArrayList<>();
        ParameterBuilder userId = new ParameterBuilder();
        userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(userId.build());
        return pars;
    }
}

swagger3配置（yml和java）

.yml

spring.mvc.pathmatch.matching-strategy=ant_path_matcher   //springboot 低版本要加
springfox.documentation.swagger-ui.base-url= /documentation
springfox.documentation.swagger-ui.enabled=true
 

 java配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.time.LocalDate;

@Configuration
public class Swagger3Config {
    @Bean
    public Docket petApi() {
        ApiInfo apiInfo = new ApiInfoBuilder().title("Spring Boot swagger3 整合")
                .contact(new Contact("IT实验室", "https://tanli.com", "[email protected]"))
                .description("Spring Boot 版本2.7、Swagger3 整合")
                .license("Apache 2.0")
                .licenseUrl("https:///spring-boot-swagger3-tutorial/main/LICENSE")
                .version("1.0")
                .termsOfServiceUrl("服务条款URL")
                .build();
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .directModelSubstitute(LocalDate.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .enableUrlTemplating(true);
    }
}

三、注解

注意箭头左边为swagger2,右边为swagger3

@Api → @Tag
 
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
 
@ApiImplicitParam → @Parameter
 
@ApiImplicitParams → @Parameters
 
@ApiModel → @Schema
 
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
 
@ApiModelProperty → @Schema
 
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
 
@ApiParam → @Parameter
 
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
 

四、路径：

 

线路
    pom引入->application配置-->java代码拦截配置--->启动参数

想了解更多，关注wx视频号：石工记，DouY:石工记 看视频更直观