knife4j 2.x 升级 3.x 版本后自定义文档不生效解决【附自定义响应状态码配置】

2023-10-22 09:37:22

问题 knife4j 2.0.7 升级 3.0.3 后自定义文档消失

这是因为knife4j3的版本是针对OpenAPI3来提供的，但是依赖的springfox3虽然说同时向下兼容OpenAPI2和OpenAPI3，但是并没有兼容好，所以，如果开发者在使用的时候，注解什么的还是用的OpenAPI2的注解的话，就继续用knife4j的2.x版本好了，如果用knife4j3.x的版本的话，创建Docket对象的时候必须指定使用OAS_30

3.0.3 配置类注解有所改变。3.0.3 配置 Docket 需指定文档类型为 DocumentationType.OAS_30

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        // ...
        .build()
        // 构建扩展插件-自定义文档 group
        .extensions(openApiExtensionResolver.buildExtensions("doc-knife4j-1.0.0"))
        .groupName("Typos Admin接口文档V1.0");
}

自定义文档属于增强模式功能

解决方案-配置步骤：

1. 引入配置 application.yaml

knife4j:
  enable: true # 开启增强模式
  documents: # 文档配置，可配置多个分组
    - group: doc-knife4j-1.0.0
      name: knife4j 学习文档
      locations: classpath:markdown/knife4j/*

2. 修改配置类 SwaggerConfig

注入 Bean 对象 OpenApiExtensionResolver

Knife4j 提供的扩展类，在构建 Docket 对象后可开启增强模式扩展插件，比如本示例中的自定义文档。

private final OpenApiExtensionResolver openApiExtensionResolver;

@Autowired
public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
    this.openApiExtensionResolver = openApiExtensionResolver;
}

2、在 Docket 对象构建后，通过调用 Docket 对象的 extensions 方法进行插件赋值

插件赋值需要调用 OpenApiExtensionResolver 提供的 buildExtensions 方法，该方法需要一个逻辑分组名称，就是开发者在 yaml 配置文件中配置的 group 名称

@Bean
public Docket api() {
	//return new Docket(DocumentationType.SWAGGER_2)
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        // ...
        .build()
        // 构建扩展插件-自定义文档 group
        .extensions(openApiExtensionResolver.buildExtensions("doc-knife4j-1.0.0"))
        .groupName("Typos Admin接口文档V1.0");
}

注意：extensions 里传递的参数是 yaml 配置文件中指定的 group

3. 完整配置类

参考我的代码：https://gitee.com/tyros/typos-platform

/**
 * Swagger 配置类
 *
 * @author zhangshuaiyin
 * @date 2021/5/31 21:58
 */
@Configuration
// @EnableSwagger2WebMvc // 2.x 版本使用这个注解
@EnableSwagger2 // 3.x 版本使用这个注解
public class SwaggerConfig {

    private final OpenApiExtensionResolver openApiExtensionResolver;

    /**
     * 通过该扩展给增强模式插件赋值，如自定义文档等
     *
     * @param openApiExtensionResolver Knife4j 扩展类
     */
    @Autowired
    public SwaggerConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    /**
     * 创建 typos-admin API 应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return Docket
     */
    @Bean
    public Docket adminApi() {
   		// return new Docket(DocumentationType.SWAGGER_2)
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(adminApiInfo())
                .select()
                // 标注@Api等注解的接口代码路径
                .apis(RequestHandlerSelectors.basePackage("com.typos.admin.controller"))
                .paths(PathSelectors.any())
                .build()
                // 构建扩展插件-自定义文档 group
                .extensions(openApiExtensionResolver.buildExtensions("doc-knife4j-1.0.0"))
                .groupName("Typos Admin接口文档V1.0");
    }


    /**
     * 创建 typos-admin API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/doc.html
     *
     * @return ApiInfo
     */
    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("Typos API")
                .description("Typos 后台管理接口文档")
                //服务条款网址
                .termsOfServiceUrl("https://www.yuque.com/zhangshuaiyin")
                .version("1.0")
                .contact(new Contact("typos", "http://127.0.0.1/", "594983498@qq.com"))
                .build();
    }
}

补充：全局响应状态码

即在这里将自定义的响应状态消息显示在 Swagger 文档中，这属于 Swagger 自身的功能。

具体配置如下，BaseMessage 为自定义的响应类。

knife4j 3.0.3 较 2.0.7 的中 Swagger 版本有所不同，对于 Swagger 自带的自定义响应状态 API 也不同。

knife4j 2.0.7 自定义响应状态列表

knife4j 2.0.7 对应 Swagger 版本中响应状态类为 ResponseMessage，其中响应码 code 类型为 int，响应信息为 message。

@Bean
public Docket api() {
    //添加全局响应状态码
    List<ResponseMessage> responseMessageList = new ArrayList<>();
    Arrays.stream(BaseMessage.values()).forEach(errorEnums -> {
        responseMessageList.add(
            new ResponseMessageBuilder().code(Integer.parseInt(errorEnums.getCode())).message(errorEnums.getMessage()).responseModel(
                new ModelRef(errorEnums.getMessage())).build()
        );
    });

    return new Docket(DocumentationType.SWAGGER_2)
        // 添加全局响应状态码
        .globalResponseMessage(RequestMethod.GET, responseMessageList)
        .globalResponseMessage(RequestMethod.PUT, responseMessageList)
        .globalResponseMessage(RequestMethod.POST, responseMessageList)
        .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
        .apiInfo(apiInfo())
        .select()
        //标注@Api等注解的接口代码路径
        .apis(RequestHandlerSelectors.basePackage("com.typos.admin.controller"))
        .paths(PathSelectors.any())
        .build()
        .extensions(openApiExtensionResolver.buildExtensions("1.0"))
        .groupName("Typos Admin接口文档V1.0");
}

knife4j 3.0.3 自定义响应状态列表

knife4j 3.0.3 对应 Swagger 版本中响应状态类为 Response，状态码 code 为 String，响应信息为 description。

@Bean
public Docket adminApi() {
    // 添加全局响应状态码
    List<Response> responseMessageList = new ArrayList<>();

    // 根据 BaseMessage 获取自定义响应码
    Arrays.stream(BaseMessage.values()).forEach(
        errorEnums -> responseMessageList.add(new ResponseBuilder()
                                              .code(errorEnums.getCode())
                                              .description(errorEnums.getMessage())
                                              .build()));

    return new Docket(DocumentationType.SWAGGER_2)
        // 添加全局响应状态码，可根据不同系统定义不同的响应码信息
        .globalResponses(HttpMethod.GET, responseMessageList)
        .globalResponses(HttpMethod.PUT, responseMessageList)
        .globalResponses(HttpMethod.POST, responseMessageList)
        .globalResponses(HttpMethod.DELETE, responseMessageList)
        .apiInfo(adminApiInfo())
        .select()
        // 标注@Api等注解的接口代码路径
        .apis(RequestHandlerSelectors.basePackage("com.typos.admin.controller"))
        .paths(PathSelectors.any())
        .build()
        // 构建扩展插件-自定义文档 group
        .extensions(openApiExtensionResolver.buildExtensions("doc-knife4j-1.0.0"))
        .groupName("Typos Admin接口文档V1.0");
}

码农公寓