新端点在测试中导致 IllegalStateException:无效的 MIME 类型 "headers":不包含“/”

New endpoint causes IllegalStateException in test: Invalid mime type "headers": does not contain '/'

我在我的 Swagger v2 规范中添加了一个新的端点,它被用于 Java 8 Spring-Boot 应用程序,使用 SpringFox 进行代码生成。

代码生成成功,app编译通过,但是@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 '/'

根据跟踪,我认为问题出在这个端点:

  /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"

为什么代码生成和构建工作但执行不工作?

规范中存在 语法错误 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 解释为媒体类型(这是它在此处所期望的);一个有效的媒体类型应该在中间有一个 /;这正是错误消息所说的内容。

声明响应 header 的正确方法 是:

      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"

这样,定义被正确拾取并且响应 header 出现在 Swagger 编辑器中生成的 HTML 中。