springdoc中的默认响应类

Posted 2023-03-10

【中文标题】springdoc中的默认响应类

【英文标题】：Default response class in springdoc

【发布时间】：2020-07-07 05:12:36

【问题描述】：

我正在尝试为我的 API 中的所有端点添加一个默认错误模型，以获取一些错误代码。

我通过阅读以下问题找到了部分解决方案：

Springfox -> Springdoc: How to expose additional models https://github.com/springdoc/springdoc-openapi/issues/381

这是我为该自定义创建的 bean：

    @Bean
    public OpenApiCustomiser customOpenApiCustomiser() 
        return openApi -> 
            openApi.getPaths().values().forEach(pathItem -> pathItem.readOperations().forEach(operation -> 

                Schema sharedErrorSchema = ModelConverters.getInstance()
                        .read(Error.class)
                        .getOrDefault("Error", new Schema());

                MediaType sharedMediaType = new MediaType().schema(sharedErrorSchema);
                Content sharedContent = new Content()
                        .addMediaType(APPLICATION_JSON_VALUE, sharedMediaType);

                ApiResponses apiResponses = operation.getResponses();

                ApiResponse response = new ApiResponse()
                        .description("Unhandled server error")
                        .content(sharedContent);
                apiResponses.addApiResponse("500", response);
            ));
        ;
    

我的错误类看起来像：

public class Error 
    private String message;
    private List<ErrorItem> errorItems;

问题是当我在 swagger-ui 中打开一个端点定义时，我收到以下错误：

Could not resolve reference: Could not resolve pointer: /components/schemas/ErrorItem does not exist in document

如何定义 ErrorItem 的架构，使其可用于 swagger-ui？

我正在使用：

Spring Boot => 2.2.4.Release springdoc-openapi-ui => 1.3.0 springdoc-openapi-security => 1.3.0

【参考方案1】：

我遇到了类似的问题，今天解决了：

首先您必须将所有 java 类型添加到组件中：

// add Error and ErrorItem to schema
openApi.getComponents().getSchemas().putAll(ModelConverters.getInstance().read(Error.class));
openApi.getComponents().getSchemas().putAll(ModelConverters.getInstance().read(ErrorItem.class));

然后您必须创建一个 Schema-Ref 以在您的响应中使用它：

// add default responses
// Ref to Error-Object (added in step above)
Schema errorResponseSchema = new Schema();
errorResponseSchema.setName("Error");
errorResponseSchema.set$ref("#/components/schemas/Error");

现在你可以使用这个 ref。在这个例子中，我只对 BadRequest 使用错误，所有其他默认响应不使用模式。根据需要更改它:-)

openApi.getPaths().values().forEach(pathItem -> pathItem.readOperations().forEach(operation -> 
  ApiResponses apiResponses = operation.getResponses();
  apiResponses.addApiResponse("400", createApiResponse("BadRequest", errorResponseSchema));
  apiResponses.addApiResponse("403", createApiResponse("Forbidden", null));
  apiResponses.addApiResponse("404", createApiResponse("Not Found", null));
  apiResponses.addApiResponse("500", createApiResponse("Server Error", null));
));

createApiResponse 只是一个简单的私有函数：

private ApiResponse createApiResponse(String message, Schema schema) 
  MediaType mediaType = new MediaType();
  mediaType.schema(schema);
  return new ApiResponse().description(message)
                .content(new Content().addMediaType(org.springframework.http.MediaType.APPLICATION_JSON_VALUE, mediaType));

确保为您的 Error.class 获得正确的导入，默认情况下它将是 java.lang.Error。

【讨论】：

在创建 openApi bean 时，路径将为空。您用于自定义 openApi 对象路径的钩子是什么，即执行 openApi.getPaths().values().forEach(pathItem -> ),

这是一篇很棒的帖子。很有帮助。谢谢！

是否有类似 ModelConverters 的东西用于从方法中读取参数模型？