Question

我正在寻找根据JSON API记录其余API响应的最佳方法，以及如何在Swagger YAML文档中对其进行描述。

我的API会收到一个单词和一个URL列表，并返回给定单词出现在所提供的每个网站中的次数。对于成功的回应，我的第一个看法是：

{
    "data": {
        "foo": {
            "http://www.foobar.com": 12,
            "http://www.bar.com": 0
        }
    }
}

使用单词和URL作为property names。

我想知道根据JSON API是否是一种好的做法，如果是，那么如何在Swagger YAML中进行记录：

swagger: '2.0'
info:
  description: How many times a given word appears in each site provided? This API answer it
  version: 1.0.0
  title: WordApp
  contact:
    email: foo@bar.com

  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

paths:
  /:
    get:
      summary: returns how many times a given word appears in each provided URL
      description: |
        By passing in the appropriate options, you can search for
        the number of occurrences of a given word in each URL provided
      produces:
      - application/json
      parameters:
      - in: query
        name: word
        description: pass a word for looking up its occurrences in each site
        required: true
        type: string
      - in: query
        name: url
        description: a list of valid URLs
        type: string
        required: true
      responses:
        200:
          description: search results matching criteria
          schema:
            type: array
            items:
              $ref: '#/definitions/Data'
        500:
          description: Internal Server Error
definitions:
  Data:
    type: object
    required:
    - word
    - url
    - value
    properties:
      word:
        type: string
        example: Brazil
      url:
        type: string
        example: 'https://www.nytimes.com/'
      value:
        type: integer
        example: 12

如果这不是最佳做法，那么建模响应的更好方法是什么？

JSON API属性名称和Swagger文档，用于正确的响应建模

0 个答案: