Forum Discussion

byoungman's avatar
byoungman
Frequent Visitor
3 years ago

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
Swagger Editor
  • dsinghvi77's avatar
    dsinghvi77
    Occasional Contributor
    3 years ago

    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's avatar
      dsinghvi77
      Occasional Contributor
      3 years ago

      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.