Listing Response Types

By default, Swashbuckle will generate a “200” response for every operation. Additionally, if an action returns a response DTO (as a specific type or ActionResult<T>), then a corresponding schema will be included with the “200” response definition. If you need to specify different status codes and/or additional responses, or you have actions that return IActionResult, you can annotate individual actions with explicit response attributes or you can apply application-wide API Conventions.

Explicit Responses

To specify explicit responses, you can decorate actions (or controllers) with the [ProducesResponseType] and [ProducesDefaultResponseType] attributes that come with ASP.NET Core. For example, given the following action method:

Swashbuckle will generate the following responses:

Note

With this approach, you have to include an attribute for all respones, including the “2xx” response. In other words, you can use the default responses generated by Swashbuckle or you can provide explicit responses, but you can’t use a mixture of both.

API Conventions

Web API conventions, available in ASP.NET Core 2.2 and later, include a way to extract common documentation conventions and apply them to multiple actions, controllers, or all controllers within an assembly. They function as a substitute for decorating individual actions with explicit responses, as shown above. For example, if all actions with the word “Create” in their name ought to return a HTTP status of 201 Created or 400 Bad Request, you could codify that convention in a C# class and apply it for documentation purposes. In fact, this exact convention is captured in the DefaultApiConventions class provided with ASP.NET Core.

To apply the default conventions (or your own custom type), you can decorate controllers with the [ApiConventionType] attribute:

In this case, Swashbuckle will generate the following responses: