Ask a Question

Response Object Question

byoungman
Frequent Visitor

Response Object Question

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
2 REPLIES 2
dsinghvi77
Occasional Contributor

@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':
          descriptionOK
          content:
            'application/json:':
              schema:
                typearray
                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
Occasional Contributor

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

cancel
Showing results for 
Search instead for 
Did you mean: