开机自检"try it out"在 Swagger 3.0 UI 中不起作用

Question

我已经设置了一个Swagger文档，它在UI中看起来不错。但是，当我使用"试用"功能时，我收到以下错误：

SyntaxError: Unexpected token # in JSON at position 0

我的 Swagger 文档的相关部分如下所示：

post:
      summary: Creates a new cinema
      operationId: addCinema
      consumes: [ application/json ]
      parameters:
        - name: name
          in: body
          description: Name of the cinema
          schema:
            type: string
          example: "Bad cinema"
        - name: description
          in: body
          description: Description of the cinema
          schema:
            type: string
          example: "A pretty terrible cinema"
        - name: capacity
          in: body
          description: Capacity of the cinema
          schema:
            type: number
          example: 100
      responses:
        201:
          description: Creates the cinema
        400:
          description: 'Invalid request'

知道为什么我会看到此错误吗？我想也许正文正在发送 HTML 而不是 JSON，但我无法弄清楚为什么会这样？

Answer 1

您的定义无效，它混合了 OpenAPI 2.0 和 3.0 关键字。

在 OpenAPI 2.0 ( swagger: '2.0' ( 中，只能有一个in: body参数，如果主体是对象，则参数schema应定义对象结构。

因此，如果您要发布此 JSON：

{
  "name": "foo",
  "description": "bar",
  "capacity": 100
}

您的 body 参数应如下所示：

      parameters:
        - in: body
          name: cinema
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
                example: Bad cinema
              description:
                type: string
                example: A pretty terrible cinema
              capacity:
                type: integer
                example: 100

或者，如果将内联架构提取到definitions中的命名架构中：

      parameters:
        - in: body
          name: cinema
          required: true
          schema:
            $ref: '#/definitions/Cinema'
....
definitions:
  Cinema:
    type: object
    properties:
      name:
        type: string
        example: Bad cinema
      description:
        type: string
        example: A pretty terrible cinema
      capacity:
        type: integer
        example: 100