title: JSON API property names and Swagger documentation for proper response modeling
body: <p>I'm seeking the best way for documenting my rest API response according to JSON API and also how to describe it in Swagger YAML documentation.</p>
  
  <p>My API receives a word and a list of URLs and returns how many times the given word appears in each website provided. My first take for the successful response was:</p>
  
  <pre><code>{
      "data": {
          "foo": {
              "http://www.foobar.com": 12,
              "http://www.bar.com": 0
          }
      }
  }
  </code></pre>
  
  <p>Using the word and the URLs as <a href="https://stackoverflow.com/questions/2065841/json-best-practice-for-property-names">property names</a>.</p>
  
  <p>I'd like to know if it is a good practice according to JSON API and if yes, how to document it in Swagger YAML:</p>
  
  <pre><code>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
  </code></pre>
  
  <p>If it is not the best practice, what would be a better way of modeling my response?</p>