Response Object Question

[byoungman]

Good Morning,

I am new to Swagger and am currently working on documenting an API that I just developed for my company. My question concerns the swagger.yaml Responses object.

The return response from my api is a nested json object - see sample below. I'm thinking I should use schema => type: array but not exactly sure how to detail this in the yaml file.

Sample Response JSON:

{
  "results":{
    "value0":"Company One",
      "matches0":[
      {
        "matchedNameId":"2861495",
        "matchedName":"Company One Inc",
        "certainty":"1.0",
        "duns":"xxxxx",
        "parentDuns":"yyyy",
        "annualRevenue":"$1,797,531.80",
        "country":"United States",
        "crsCode":"4",
        "location":"United States",
        "naics":"xxxx"
      }
    ],
    "value1":"Company Two Inc.",
      "matches1":[
        {
          "matchedNameId":"3423310",
          "matchedName":"Company Two Inc",
          "certainty":"1.0",
          "duns":"xxxx",
          "parentDuns":"",
          "annualRevenue":"$1,646,675.00",
          "country":"United States",
          "crsCode":"xx",
          "location":"",
          "naics":"xxxx"
        }
      ],
      "metrics":{
        "Total time for run (Total Seconds)":"1.269741",
        "Average Query Time (seconds)":"0.0015",
        "Total Rows Processed":"15",
        "Highest Row Count":"9",
        "Average Row Count":"7.5",
        "Highest matching index":"8",
        "Average index":"1.7",
        "Total Num Errors":"0",
        "Total Strings To Match":"2",
        "Total Matches":"30"
      }
    }
}

 swagger.yaml setting

      responses:

        '200':

          description: OK

          content:

            'application/json:':

              schema:

                type: array

                items:

                  type: string

This block doesn't seem to be correct but I'm not sure what it should be.

Thanks,

Bill

[dsinghvi77]

@byoungman I think you should update the JSON Model returned to your endpoint to something like this: 

{
    "results": [
         {
              "value": "Company Zero", 
              "matches": {
                "matchedNameId": "2861495",
              }
         }, 
         {
             "value": "Company One", 
             "matches": {
                "matchedNameId": "3423310",
             }
         },
    ]
    "metrics": {
      "metric_one": "value"
    }
}

You don't want your client to be relying on specific key values such as "value0" or "matches0" because that can't be modeled in the spec (it is dynamic depending on search results) so you want to group those two things into one object. 

The JSON I wrote out for you can be modelled like this in Open API: 

responses:
        '200':
          description: OK
          content:
            'application/json:':
              schema:
                type: array
                items:
                  type: $ref/components/schemas/MyResponse

components: 
  schemas: 
     MyResponse: 
        properties: 
          result: 
            schema:
                type: array
                items: 
                  properties: 
                     value: string
                     matches: "$ref/components/schemas/MyResponseMatch"
                     metrics:"$ref/components/schemas/MyMetricsObj" # not shown
       MyResponseMatch: 
          schema: 
             type: object
             properties: 
                matchNameId: string

[dsinghvi77]

My team is making it easier to write specs + generate high quality code with an alternative spec. That being said, we'd be happy to help you with your Open API Spec so feel free to reach us at email.