openapi生成器不会使用Spring Webclient为Java客户端生成响应头

Question

我们有一个openapi文件（已验证），用于声明响应头，例如。

    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "type": "object",
          "properties": {
            "results": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/CourseV2"
              }
            },
            "paging": {
              "$ref": "#/definitions/PagingInfo"
            }
          },
          "required": [
            "results"
          ]
        },
        "headers": {
              "X-RateLimit-Limit": {
                "type": "integer",
                "description": "Request limit per hour."
              },
              "X-RateLimit-Remaining": {
                "type": "integer",
                "description": "The number of requests left for the time window."
              },
              "X-RateLimit-Reset": {
                "type": "string",
                "format": "date-time",
                "description": "The UTC date/time at which the current rate limit window resets."
              }              
          }           
      },

使用openapi生成器项目（maven或cli）生成的java webclient客户端，调用的返回类型不包括响应头，ApiClient类中的invokeAPI方法也不允许访问响应头。实际上，ApiClient invoke方法返回的是返回类型的Mono/Flux，因此不允许获取响应头

public <T> Mono<T> invokeAPI(String path, HttpMethod method, Map<String, Object> pathParams, MultiValueMap<String, String> queryParams, Object body, HttpHeaders headerParams, MultiValueMap<String, String> cookieParams, MultiValueMap<String, Object> formParams, List<MediaType> accept, MediaType contentType, String[] authNames, ParameterizedTypeReference<T> returnType) throws RestClientException {
    final WebClient.RequestBodySpec requestBuilder = prepareRequest(path, method, pathParams, queryParams, body, headerParams, cookieParams, formParams, accept, contentType, authNames);
    return requestBuilder.retrieve().bodyToMono(returnType);
}

据我所知，使用Spring Webclient访问响应头的唯一方法是使用toEntity，它提供了一个ResponseEntity方法（以及.getHeaders），而不是BodyToNo。

我错过了什么吗？

Answer 1

基于Spring的openapi生成器模板并没有提到响应头，但是这些头是由生成器核心引擎支持的，一些生成器的模板包含了对它们的 /some/支持。

此外，Swagger注释用于例如Java-Spring模板，允许指定给定响应的响应头。

到目前为止还不错。可以尝试增强选定生成器的模板。如果Java /Spring生成器，它将https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache

然而，当前的openapi生成器数据模型似乎有点不正确。

首先，响应头绑定到一个方法，而不是该方法的特定响应。这意味着一个人不能为不同的响应使用不同的头（例如，一个用于200，另一个用于412），这似乎是一个严重的缺陷。

其次，为了使生成器产生头（特别是枚举）所必需的类型，这些头不应该使用内置模式，所有模式都要放在#/组件/模式/中，然后从相应的头引用：

components:
  headers:
    Repeatability-Result:
      description: |
        a header to implement server-side machinery for idempotency of requests
        complying to OASIS Repeatable Requests Version 1.0
        https://docs.oasis-open.org/odata/repeatable-requests/v1.0/repeatable-requests-v1.0.html
      schema:
        $ref: '#/components/schemas/RepeatabilityResult'
      required: true
  ...
  schemas:
    RepeatabilityResult:
      description: |
        a header to implement server-side machinery for idempotency of requests
        complying to OASIS Repeatable Requests Version 1.0
        https://docs.oasis-open.org/odata/repeatable-requests/v1.0/repeatable-requests-v1.0.html
      type: string
      enum:
        - accepted
        - rejected

接下来，生成的类型不包括在{{{imports}}中，因此需要手动处理。

此外，在生成器类型定义中，标题类型描述似乎不可撤销地丢失了。

最后，现在我不明白一个正确的Java/WebFlux特定API方法定义应该是什么样子。

我可以在@apisresponse定义中包含响应负责人，如下所示：

@ApiResponse(value = 204,
    responseHeaders = {
        @ResponseHeader(name = "ETag", response = String.class),
        @ResponseHeader(name = "Repeatability-Result", response = org.example.RepeatabilityResult.class)
    },
    message = ....
)
<webflux-specific API method declaration>

但是它似乎只是为了提供信息，并没有带来任何新的功能。人们仍然需要手动为响应添加必要的标题，而不需要框架的任何支持/验证。

我可以向OpenAPI生成器提交一个bug，但首先我想了解一个合适的解决方案是什么样子的。