you may use Extension Methods Which I think are more cleaner way to document API endpoints. This way you can define generic response methods for each endpoint.
For this you need to install the following packages :
Swashbuckle.AspNetCore and Swashbuckle.AspNetCore.Annotations
using Microsoft.AspNetCore.Authorization;
using Swashbuckle.AspNetCore.Annotations;
public static class MinimalAttributeExtensions
{
public static RouteHandlerBuilder AllowAnonymous(this RouteHandlerBuilder endpoint)
{
endpoint.WithMetadata(new AllowAnonymousAttribute());
return endpoint;
}
public static RouteHandlerBuilder Authorize(this RouteHandlerBuilder endpoint, string policy = null, string[] roles = null, params string[] schemes)
{
var authorizeAttribute = new AuthorizeAttribute();
if (!string.IsNullOrEmpty(policy))
{
authorizeAttribute.Policy = policy;
}
if (roles != null && roles.Any())
{
authorizeAttribute.Roles = string.Join(',', roles);
}
if (schemes != null && schemes.Any())
{
authorizeAttribute.AuthenticationSchemes = string.Join(',', schemes);
}
endpoint.WithMetadata(authorizeAttribute);
return endpoint;
}
public static RouteHandlerBuilder AddMetaData<T>(this RouteHandlerBuilder endpoint, string tag, string summary = null, string description = null)
{
endpoint.WithTags(tag);
endpoint.WithMetadata(new SwaggerOperationAttribute(summary, description));
endpoint.WithMetadata(new SwaggerResponseAttribute(200, type: typeof(T)))
.WithMetadata(new SwaggerResponseAttribute(500, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(400, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(404, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(422, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(304, type: typeof(ErrorResponseModel)));
return endpoint;
}
public static RouteHandlerBuilder AddMetaData(this RouteHandlerBuilder endpoint, string tag, string summary = null, string description = null)
{
endpoint.WithTags(tag);
endpoint.WithMetadata(new SwaggerOperationAttribute(summary, description));
endpoint.WithMetadata(new SwaggerResponseAttribute(500, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(400, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(404, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(422, type: typeof(ErrorResponseModel)))
.WithMetadata(new SwaggerResponseAttribute(304, type: typeof(ErrorResponseModel)));
return endpoint;
}
}
following is an example of how to use these extension Methods:
app.MapGet(“/books”, async (BooksDB db) =>
{
return await db.Books.ToListAsync()
})
.Authorize(policy : "AdminOnly", roles : new string[] {1,2}, schemes: "Bearer")
.AddMetaData<List<Book>>
(
tag : "Books",
summary : "Get All Books",
description : "Get All Books in List, Roles Allowed => Admin Only"
);
The .AddMetaData<T>
here represents the response model for success, this will also add to the response documentation of this endpoint. In this case it is List<Book>
.