新端点在测试中导致 IllegalStateException：无效的 mime 类型“headers”：不包含 '/'

Question

我在我的 Swagger v2 规范中添加了一个新端点，该端点正在使用 SpringFox 生成代码的 Java 8 Spring-Boot 应用程序中使用。

代码生成成功，应用编译成功，但@RestController无法启动。所有测试和正常启动序列都失败并显示以下错误消息，即使是与新端点无关的错误消息：

[ERROR] someUnitTest(com.mycompany.api.corporate.server.controller.SomeControllerTest) Time elapsed: 0 s <<< ERROR!
java.lang.IllegalStateException: Failed to load ApplicationContext
Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'documentationPluginsBootstrapper' defined in URL [jar:file:/root/.m2/repository/io/springfox/springfox-spring-web/2.8.0/springfox-spring-web-2.8.0.jar!/springfox/documentation/spring/web/plugins/DocumentationPluginsBootstrapper.class]: Unsatisfied dependency expressed through constructor parameter 1;
nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'webMvcRequestHandlerProvider' defined in URL [jar:file:/root/.m2/repository/io/springfox/springfox-spring-web/2.8.0/springfox-spring-web-2.8.0.jar!/springfox/documentation/spring/web/plugins/WebMvcRequestHandlerProvider.class]: Unsatisfied dependency expressed through constructor parameter 1;
nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'requestMappingHandlerMapping' defined in class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]: Invocation of init method failed; nested exception is java.lang.IllegalStateException: Invalid mapping on handler class [com.mycompany.api.corporate.server.controller.OrderController]: public org.springframework.http.ResponseEntity com.mycompany.api.corporate.server.controller.OrderController.finishOrder(com.mycompany.api.corporate.server.model.CustomerData,java.lang.String)
Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'webMvcRequestHandlerProvider' defined in URL [jar:file:/root/.m2/repository/io/springfox/springfox-spring-web/2.8.0/springfox-spring-web-2.8.0.jar!/springfox/documentation/spring/web/plugins/WebMvcRequestHandlerProvider.class]: Unsatisfied dependency expressed through constructor parameter 1;
nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'requestMappingHandlerMapping' defined in class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]: Invocation of init method failed;
nested exception is java.lang.IllegalStateException: Invalid mapping on handler class [com.mycompany.api.corporate.server.controller.OrderController]: public org.springframework.http.ResponseEntity com.mycompany.api.corporate.server.controller.OrderController.finishOrder(com.mycompany.api.corporate.server.model.CustomerData,java.lang.String)
Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'requestMappingHandlerMapping' defined in class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]: Invocation of init method failed; nested exception is java.lang.IllegalStateException: Invalid mapping on handler class [com.mycompany.api.corporate.server.controller.OrderController]: public org.springframework.http.ResponseEntity com.mycompany.api.corporate.server.controller.OrderController.finishOrder(com.mycompany.api.corporate.server.model.CustomerData,java.lang.String)
Caused by: java.lang.IllegalStateException: Invalid mapping on handler class [com.mycompany.api.corporate.server.controller.OrderController]: public org.springframework.http.ResponseEntity com.mycompany.api.corporate.server.controller.OrderController.finishOrder(com.mycompany.api.corporate.server.model.CustomerData,java.lang.String)
Caused by: org.springframework.http.InvalidMediaTypeException: Invalid mime type "headers": does not contain '/'
Caused by: org.springframework.util.InvalidMimeTypeException: Invalid mime type "headers": does not contain '/'

鉴于trace，我认为问题出在这个端点上：

  /order/{id}/finish:
    post:
      tags:
      - Order
      summary: TODO
      description: TODO
      operationId: finishOrder
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        required: true
        description: TODO
        type: string
      - in: body
        name: customerData
        required: true
        description: TODO
        schema:
          $ref: "#/definitions/CustomerData"
      responses:
        201:
          description: Account created
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            application/json:
              code: "00000"
            headers:
              Location:
                type: string
                description: Resource location to be used for later
        400:
          description: >
            Failed to create the account.
            See error code and message in object.
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            application/json:
              code: "31120"
              message: "Last name is too long"

为什么代码生成和构建工作而不是执行？

Answer 1

规范中有一个语法错误，Swagger Editor 或 Codegen 插件没有发现该错误：

      responses:
        201:
          description: Account created
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            application/json:
              code: "00000"
            headers:  # This is the problem: response headers should not be defined here
              Location:
                type: string
                description: Resource location to be used for later

应用程序将第一个变体中的headers 解释为媒体类型（这是它在此处所期望的）；一个有效的媒体类型应该在中间有一个/；这正是错误消息所说的内容。

声明响应头的正确方法是：

      responses:
        201:
          description: Account created
          schema:
            $ref: "#/definitions/StatusMessage"
          headers:
            Location:
              type: string
              description: Resource location to be used for later
          examples:
            application/json:
              code: "00000"

这样，定义被正确提取，响应标头出现在 Swagger 编辑器中生成的 HTML 中。