Springboot集成springFox-Swagger3并通过Yapi做接口管理

添加Swagger2依赖

    
        io.springfox
        springfox-boot-starter
        3.0.0
    
1
2
3
4
5

添加注解

启用Swagger3

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableOpenApi //启用swagger3
@ConditionalOnClass
@SpringBootApplication
public class DemoApplication {
    public static final Logger logger = LoggerFactory.getLogger(DemoApplication.class);

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

swagger分组配置(可选)

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 这里指定走Swagger3标准,你仍然可以指定走Swagger2标准
                .groupName("第一组") // 定义组名
                .apiInfo(apiInfo())
                .select()
                // 指定该组扫描哪些包下面的接口
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("XX平台API接口文档")
                //创建人
                .contact(new Contact("今天例外", "https://blog.csdn.net/qq_15022971/article/details/126606500?spm=1001.2014.3001.5501",
                        "xxxxxx@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("系统API描述")
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

controller层

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@Api(tags = "测试接口管理-springFoxSwagger3")
@RestController
@RequestMapping("/test")
public class TestController {
    
    @ApiOperation("测试接口")
    @PostMapping("/getCarInfo")
    public CarInfoResponseDTO test (@RequestBody CarInfoRequestDTO carInfoRequestDTO) {
        return new CarInfoResponseDTO();
    }
} 	
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

入参添加注解

// 入参添加注解
@Data
@ApiModel(value = "CarInfoRequestDTO", description = "车辆信息DTO")
public class CarInfoRequestDTO implements Serializable {

    @ApiModelProperty(value = "车架码(vin码)", name = "vin", dataType = "String")
    private String vin;

    @ApiModelProperty(value = "车牌号", name = "plateNo", dataType = "String")
    private String plateNo;

    @ApiModelProperty(value = "号牌种类", name = "plateType", dataType = "String")
    private String plateType;

    @ApiModelProperty(value = "厂牌型号", name = "vehicleName", dataType = "String")
    private String vehicleName;

    @ApiModelProperty(value = "订单id", name = "orderId", dataType = "String")
    private String orderId;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

返参添加注解

// 返参添加注解
@Data
@ApiModel(value = "CarInfoResponseDTO", description = "车辆信息响应DTO")
public class CarInfoResponseDTO {

    @ApiModelProperty(value = "车架码(vin码)", name = "vin", dataType = "String")
    private String vin;

    @ApiModelProperty(value = "车牌号", name = "plateNo", dataType = "String")
    private String plateNo;

    @ApiModelProperty(value = "发动机号", name = "engNO", dataType = "String")
    private String engNO;

    @JsonFormat(
            pattern = "yyyy-MM-dd",
            timezone = "GMT+8"
    )
    @JsonSerialize(
            using = LocalDateSerializer.class
    )
    @JsonDeserialize(
            using = LocalDateDeserializer.class
    )
    @ApiModelProperty(value = "初登日期", name = "firstRegisterDate", dataType = "LocalDate")
    private LocalDate firstRegisterDate;

    @ApiModelProperty(value = "新车购置价", name = "purchasePrice", dataType = "BigDecimal")
    private BigDecimal purchasePrice;

    @ApiModelProperty(value = "座位数", name = "seat", dataType = "Integer")
    private Integer seat;

    @ApiModelProperty(value = "核定载质量", name = "vehicleCapacity", dataType = "BigDecimal")
    private BigDecimal vehicleCapacity;

    @ApiModelProperty(value = "行业车型编码", name = "hyModelCode", dataType = "String")
    private String hyModelCode;

    @ApiModelProperty(value = "整车车型编码", name = "jyModelCode", dataType = "String")
    private String jyModelCode;

    @ApiModelProperty(value = "品牌型号", name = "brandModel", dataType = "String")
    private String brandModel;

    @ApiModelProperty(value = "行业车型名称", name = "carStyleName", dataType = "String")
    private String carStyleName;

    @ApiModelProperty(value = "整车车型名称", name = "jyModelName", dataType = "String")
    private String jyModelName;

    @ApiModelProperty(value = "排量", name = "displacement", dataType = "BigDecimal")
    private BigDecimal displacement;

    @ApiModelProperty(value = "年款，格式：YYYY", name = "yearKx", dataType = "String")
    private String yearKx;

    @ApiModelProperty(value = "车辆的实际价值", name = "actualValue", dataType = "BigDecimal")
    private BigDecimal actualValue;

    @ApiModelProperty(value = "车辆的实际价值上限", name = "actualValueMax", dataType = "BigDecimal")
    private BigDecimal actualValueMax;

    @ApiModelProperty(value = "车辆的实际价值下限", name = "actualValueMin", dataType = "BigDecimal")
    private BigDecimal actualValueMin;

    @ApiModelProperty(value = "整备质量", name = "curbWeight", dataType = "BigDecimal")
    private BigDecimal curbWeight;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69