Add a default 200 response to all API paths

🛠️ Open Technologies GSoC
1

Hello @meenakshi.dhanani
I completed the first task Add default 200 response to all API paths.
Can you please review my pr?
Thank You

2

Hey @thefierycoder,
I’d like to clarify the expectation of the task listed:

  • The workspace has an API called Petstore for instance.
  • You need to be able to pull the API(yaml/json), and a default response for each of the paths(via a script).

Why this could be a utility?

  • The OpenAPI format is used to describe an API.
  • By adding a default 200 response to all API paths - it could be easier management of the API, instead of manually having to edit paths in the definition and adding default responses.

I’d suggest first getting familiar with OpenAPI, that could help understand why these utilities might be useful for someone.

2 Likes
3

Thank You for sharing the article :pray:
I’ll go through it and then update you.

1 Like
4

Hello @meenakshi.dhanani
I have gone through the article.
What I understood from your explanation is first I need to pull the API using the second collection and then pull the default response by looping through the individual path.

      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default: # Do I need to pull this default response and then update this with '200' response?
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

and then update the above default response :point_down: and then set this openapi schema to the visualizer.

paths
  /pets:
    get:
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: Request Successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"

Is it correct?

5

Hey @thefierycoder,
Almost there!
You’re right about using the second collection to pull the OpenAPI(Petstore). Now the default response is returned for response codes that aren’t defined for the particular path.
For eg. for the petstore, there are 4 APIs and for response codes other than the ones defined, we want to return an error message. With the current workflow, you’d have to manually add a default response for every API.

Some large systems have 800 APIs, imagine repeating it 800 times. This util should allow adding a default response for all APIs in Petstore.

To test if your code can do it, add another /path to the Petstore API without a default response and your code should programmatically add a default response to that path.

You can find comments on how this issue is a pain point for OpenAPI users here - Proposal: Default responses for all endpoints · Issue #521 · OAI/OpenAPI-Specification · GitHub

6

Thanks for the feedback🙏
I have some doubt regarding this:

  1. Do we need to add a default response only when the default response is not there in the API path? If it’s there then we don’t need to add a default response.
  2. If the default response is not there, then what type of default response we need to return.
    For example:
    Success default response like this
responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: Request Successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"

or an error default response

 responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error
7

A default response is a response returned for cases not covered for a particular API path. You need to put yourself in the shoes of the API producer, and reason the cases for a default response.

Read more about default responses - Describing Responses in this section. That should help :slight_smile:

1 Like
8

Thanks
I will do my best🙂

9

Hello @meenakshi.dhanani

I made changes as suggested.
Please review my PR.

Thank You