Как добавить несколько примеров к ответу в Swagger, не нарушая Codegen? - PullRequest
Новая
       105

Как добавить несколько примеров к ответу в Swagger, не нарушая Codegen?

0 голосов
/ 11 октября 2018

Я пытался добавить примеры к своему Swagger API в соответствии с официальным документом (см. Последний кодовый блок Примеры тела запросов и ответов ), но, похоже, он не работаеткак и ожидалось.

Учитывая следующий минимальный пример: 

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: 

@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 отсутствует, а тип возвращаемого значения неправильный!Кроме того, это не компилируется в Swagger Editor : свойство responses should NOT have additional properties.

Я изменил его, чтобы получить «действительный» пример в SwaggerРедактор, но сгенерированный код также неверен.См. Ниже: 

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 в качестве ключа для заголовка примера, но это мешает мне добавлять больше примеров из-за дублированного ключа.

1 Ответ

0 голосов
/ 15 октября 2018

С Хелен * комментарий :

В этом примере смешивается синтаксис OpenAPI 2.0 (swagger: '2.0') и OpenAPI 3.0 (openapi: 3.0.0),Например, content и examples являются ключевыми словами OpenAPI 3.0, но definitions является ключевым словом 2.0.

examples (форма множественного числа) не поддерживается в OpenAPI 2.0, который поддерживает только example- ознакомьтесь с руководством 2.0 для Добавление примеров .

Обходное решение, которое я нашел для этой проблемы в 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.

...