Swagger Annotations

Namespace Swashbuckle.Swagger.Annotations

All swagger configuration can be done in the applications start up config however there are times when either the API is old or for some reason you only need to document a single end point, perhaps the project is massive and core configuration changes are not possible but swagger was configured in a basic form at some point.

Annotations allow us to decorate certain methods which supports the above premise.

SwaggerOperation

This sets the operation id to what ever value you specify, this is helpful if the default is duplicated elsewhere in the API.

The operation id in OpenAPI is the field operationId: Controller_MethodName_VERB this needs to always be unique and will be used in the Swagger UI to navigate between methods.

To set this, decorate your method with:

1
[SwaggerOperation(OperationId = "Controller_MethodName_VERB")]

SwaggerResponseRemoveDefaults

This is an interesting annotation as it removes the default OK 200 response that all endpoints automagically get from swagger. This is useful when your endpoint is creating a new resource and you want to follow best practice by returning a Created 201 instead.

To set this, decorate your method with:

1
2
[SwaggerResponseRemoveDefaults]
[SwaggerResponse(HttpStatusCode.Created, "The cool thing was created.")]

References