swagger

swagger copied to clipboard

Enables defining global responses which are inherited by all server routes.

fixes #884

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• [x] Tests for the changes have been added (for bug fixes / features)
• [x] Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Other... Please describe:

What is the current behavior?

Issue Number: #884

What is the new behavior?

DocumentBuilder.addResponse has been added as a way to specify API responses globally. All server routes are then by default extending global responses.

SwaggerModule.createDocument(
  app,
  new DocumentBuilder()
    .addResponse({
      status: 500,
      description: 'Internal server error'
    }) // Same type as @ApiResponse decorator: ApiResponseOptions
   ...
)

Does this PR introduce a breaking change?

[ ] Yes
[ x] No

Other information

Any updates on this?

Looks like this is passing. Is it possible to merge it? This would be very helpful to have. @kamilmysliwiec

@kamilzki, @kamilmysliwiec Maybe we will make a merge or we are waiting for something else?

@skiryuk When I created the PR, I tried to contact with @kamilmysliwiec, but unfortunately, I've never got any response. @ronan-f I as well wish to have that helpful feature!

up

Is it possible to merge? @kamilmysliwiec

Ran into a scenario where this would be useful. Any chance this could be merged?

I also have a need for this. AFAIK currently there's no way to directly modify the components.responses element of the OpenAPI document, so It would be a nice addition. But if I understand correctly, also the intention of the PR is to apply these responses to every defined path. However, I don't think that should be the default behaviour, since as per the OpenAPI spec, the idea is for the elements in this section to be reusable rather than global.

In that case, this is very similar to how currently the security methods work, there's the individual ones that add elements to components.securitySchemes, but also addSecurityRequirements that makes a scheme global. The difference is that here that translates into simply adding a root security attribute, whereas with responses, every path operation has to be modified.

Also, another difference here is that responses in components.responses do not specify a status code (they may include it as a custom attribute but it's not part of the spec), but it must be provided when added to the response element of a path operator. With that in mind my idea for the API would be something like this:

// ResponsesObject comes from lib/interfaces/open-api-spec.interface.ts
const myResponse: ResponseObject = {
  description: "My description",
  headers: {
    // ...
  },
  content: {
    "application/json": {
      // ...
    }
    // ...
  },
  links: {
    // ...
  }
}


new DocumentBuilder()
  .addResponse(response, "MyResponseName")
  .addGlobalResponse("MyResponseName", "4XX")

So the resulting OpenAPI document would be something like this:

{
  "openapi" : "3.0.0",
  "paths" : {
    "/some/path" : {
      "get" : {
        "operationId" : "getThing",
        "responses" : {
          "200" : {
            "description" : "This is a previously defined response",
            "content" : {
              "application/xml" : {
                "schema" : {
                  "$ref" : "#/components/schemas/SomePreviouslyDefinedResponse"
                }
              }
            }
          },
          "4XX" : {
            "$ref" : "#/components/responses/MyResponseName"
          }
        }
      }
    }
  },
  "components" : {
    "responses" : {
      "MyResponseName" : {
        "description" : "My description.",
        "headers": {
          // ...
        },
        "content" : {
          "application/json" : {
            // ...
          }
        },
        "links": {
          // ...
        }
      }
    }
  }
}

Just my two pennies' worth, it would be a shame to see a SECOND pull request go stale :sweat_smile:

Any evolution in this PR?

I'm sorry to bother you, but I would like this pull request to be merged. As MatiasDuhalde upstairs said, the OpenAPI specification proves the feasibility and necessity of understanding coupling.

For example, in the Components Object section of Swagger's official documentation

Components Object holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

This paragraph comes from the OpenAPI specification v3.1 released in 2021, but this year is already 2024, this feature can not be used in nest, personal feeling will not be a little outdated?

I want to push forward with this PR merger, and it's my request alone. please.

Kinda need it too, used to do it in java and the initial PR is 3 years old :/

https://github.com/nestjs/swagger/pull/933