swagger 2.0 中 JSON 对象的模式类型是啥

Posted 2023-03-16

【中文标题】swagger 2.0 中 JSON 对象的模式类型是啥

【英文标题】：What is the schema type for JSON object in swagger 2.0swagger 2.0 中 JSON 对象的模式类型是什么

【发布时间】：2017-04-27 06:24:37

【问题描述】：

我正在借助 Swagger 2.0 编写 API 文档。我已经生成了一个 API，其中响应在一系列工作正常的书籍中。

[
    "id": 1,
    "book_name": "The Complete Reference Java8",
    "author": "Herbert Schidt",
    "genre": "Technology"
, 
    "id": 2,
    "book_name": "C Programming",
    "author": "Dennis Ritchie",
    "genre": "Technology"
]

大摇大摆

/fetchBooks:
get:
  description: |
    Returns an array of book objects.

  responses:
    200:
      description: Successful response
      schema:
        title: ArrayOfBooks
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
            book_name:
              type: string
            author:
              type: string
            genre:
              type: string

好吧，我只想在JSONObject 的一个 API 中发送一本书的详细信息，因为我尝试过的对象不起作用，所以我应该采用什么模式类型。

    "id": 1,
    "book_name": "The Complete Reference Java8",
    "author": "Herbert Schidt",
    "genre": "Technology"

大摇大摆

/fetchBook:
get:
  description: |
    Returns a book object

  parameters:
    - name: id
      in: query
      description: Books Id's
      reqrequired: true
      type: integer
      format: int

  responses:  
    200:
      description: Successful response
      schema:
        type: object <-- What type should I specify for JSONObject here
        items:
          type: object
          properties:
            id:
              type: integer
            book_name:
              type: string
            author:
              type: string
            genre:
              type: string

由于对象不工作，swagger 没有显示JSON 格式。

当前状态：

预期状态：

【参考方案1】：

  /fetchBook:
    get:
      description: |
        Returns a book object

      parameters:
        - name: id
          in: query
          description: Books Id's
          required: true
          type: integer
          format: int

      responses:  
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              id:
                type: integer
              book_name:
                type: string
              author:
                type: string
              genre:
                type: string

您遇到的问题是所需字段中的拼写错误

fallowing 是单个对象响应的正确语法

【讨论】：

我将其更正为“必需”。但是当前状态相同 i.stack.imgur.com/lM4ui.png 和预期状态应该是 i.stack.imgur.com/997tK.png

休闲链接是此答案中使用的完整 swagger 规范，link，我建议检查您的缩进或其他可能影响您代码的因素，因为此 swagger yaml 再现了您想要的响应跨度>

【参考方案2】：

提示：如果您想在多个操作中重用相同的架构 - 例如有一个Book 和一个ArrayOfBooks，您可以在definitions 部分和$ref 其他地方定义架构。

paths:
  /fetchBooks:
     get:
       ...
       responses:
         200:
           description: Successful response
           schema:
             $ref: '#/definitions/ArrayOfBooks'  # <--------
  /fetchBook:
     get:
       ...
       responses:
         200:
           description: Successful response
           schema:
             $ref: '#/definitions/Book'          # <--------

definitions:
  Book:
    type: object
    properties:
      id:
        type: integer
      book_name:
        type: string
      author:
        type: string
      genre:
        type: string
  ArrayOfBooks:
    type: array
    items:
      $ref: '#/definitions/Book'  # <--------

此外，如果这是一个正在开发的新 API 而不是现有 API，则 GET /fetchBooks 中的“获取”是多余的（GET = 获取）。考虑放弃“获取”并仅使用GET /books 和GET /book?id=...。

【讨论】：

非常感谢 Helen 提出的好方法。 +1