如何在不破坏 Codegen 的情况下向 Swagger 中的响应添加几个示例？

Question

我一直在尝试根据 official docs 向我的 Swagger API 添加示例（请参阅 请求和响应 Body 示例的最后一个代码块) 但它似乎没有按预期工作。

考虑以下最小示例：

swagger: "2.0"
info:
  description: Desc
  version: "1"
  title: Title
paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          content:
            application/json:
              schema:
                $ref: "#/definitions/StatusMessage"
              examples:
                Success without message:
                  value:
                    code: "00000"
                Success with message:
                  value:
                    code: "00000"
                    message: "All right"
definitions:
  StatusMessage:
    type: object
    description: Response with code and optional message
    properties:
      code:
        type: string
      message:
        type: string
    required:
    - code

我想提供示例回复，一个有可选的属性 message 存在，另一个没有。但是，上述 YAML 文件在生成的 API Class:

中产生了错误的结果

@ApiOperation(value = "", nickname = "stuffPost", notes = "", tags={  })
@ApiResponses(value = { 
    @ApiResponse(code = 201, message = "It worked") })
@RequestMapping(value = "/stuff",
    method = RequestMethod.POST)
default ResponseEntity<Void> stuffPost() { /*default implementation*/ }

produces 属性不存在并且 return 类型错误！此外，这不会在 Swagger Editor 中编译：responses 属性 should NOT have additional properties.

我已将其更改为在 Swagger 编辑器中获得一个 "valid" 示例，但生成的代码也是错误的。见下文：

paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            Success without message:
              code: "00000"
            Success with message:
              code: "00000"
              message: "All right"

生成的方法为：

@ApiOperation(value = "", nickname = "stuffPost", notes = "", response = StatusMessage.class, tags={  })
@ApiResponses(value = { 
    @ApiResponse(code = 201, message = "It worked", response = StatusMessage.class) })
@RequestMapping(value = "/stuff",
    produces = { "application/json", "Success without message", "Success with message" }, 
    method = RequestMethod.POST)
default ResponseEntity<StatusMessage> stuffPost() { /*default implementation*/ }

这一次，produces 属性在那里，但完全关闭了！

我怎样才能让它工作？ 如果我使用第二个版本 application/json 作为示例标题的键，它会工作，但这会阻止我添加更多由于重复键的示例。

Answer 1

来自 Helen's comment:

This example is mixing OpenAPI 2.0 (swagger: '2.0') and OpenAPI 3.0 (openapi: 3.0.0) syntax. For example, content and examples are OpenAPI 3.0 keywords, but definitions is a 2.0 keyword.

examples (plural form) are not supported in OpenAPI 2.0, which only supports example - check out the 2.0 guide for Adding Examples.

我在 OpenAPI 2.0 中找到的解决此问题的方法如下：

paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            - code: "00000"
              message: "All right"
            - code: "00000"

这显示了两个示例（标题为 0 和 1）并且不会破坏 Codegen。

如何在不破坏 Codegen 的情况下向 Swagger 中的响应添加几个示例？

How to add several examples to response in Swagger without breaking Codegen?

swagger-ui

spring-boot

swagger-2.0

swagger-editor

swagger-codegen