SpringBoot集成Swagger3

Open API

OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

Swagger

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。 国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3） swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。

1、版本

 <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

2、配置文件

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3、配置类

@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Bean
    public Docket creatApi() {
        return new Docket(DocumentationType.OAS_30)
                //设置应用编程接口信息
                .apiInfo(apiInfo())
                //设置请求参数
                .globalRequestParameters(buildHeaderParams())
                .globalResponses(HttpMethod.PUT,getGlobalResponseMessage())
                //获取选择器构建器
                .select()
                //设置选择API的方式
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //设置生成文档的路径范围
                .paths(PathSelectors.regex("/swagger3/.*"))
                .build();
    }
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("SpringBoot Example Swagger3")
                .description("SpringBoot集成Swagger Demo")
                .contact(ApiInfo.DEFAULT_CONTACT)
                .version("1.0")
                .build();
    }
    //设置请求头
    private List<RequestParameter> buildHeaderParams() {
        RequestParameterBuilder ticketPar = new RequestParameterBuilder();
        List<RequestParameter> pars = new ArrayList();
        pars.add(this.buildParam(ticketPar, "W-SEQ").build());
        pars.add(this.buildParam(ticketPar, "W-FLOW").build());
        pars.add(this.buildParam(ticketPar, "X-DEBUG").build());
        pars.add(this.buildParam(ticketPar, "X-LOGGER").build());
        pars.add(this.buildParam(ticketPar, "X-LOGGER-EVENT").build());
        return pars;
    }
    private RequestParameterBuilder buildParam(RequestParameterBuilder builder, String name) {
        return builder.name(name).description(name).in(ParameterType.QUERY)
                .query(q->q.model(m -> m.scalarModel(ScalarType.STRING))).required(false);
    }

    //生成通用响应信息
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
        return responseList;
    }
}

4、控制器

@RestController
@Api(tags = {"SwaggerTest"})
public class SwaggerTestController {

    @PutMapping("/swagger3/update")
    @ApiOperation("更新数据")
    public MvcResponse<Void> update(@RequestBody UserInputDTO inputDTO) {
        return MvcResponse.success();
    }

    @PutMapping("/swagger2/update")
    @ApiOperation("更新数据")
    public MvcResponse<Void> update2(@RequestBody UserInputDTO inputDTO) {
        return MvcResponse.success();
    }
}

5、注意事项

1. 如果不添加YAML配置项会导致,documentationPluginsBootstrapper 空指针异常。
2. 返回结构体无get、set方法会导致，swaggerUI上exapmle value 无结构体格式

参考

SpringFox Document