ardalis / ardalis/ApiEndpoints
Swagger documentation in separate class
- Dominant language
- C#
- Stars
- 3.2k
- Forks
- 232
- PR merge metrics
- No merged PRs in 30d
Description
Currently, you can document endpoint using ``SwaggerOperation`` attribute above ``HandleAsync`` method:
```cs
[SwaggerOperation(
Summary = "Submit a new article",
Description = "Enables the submission of new articles",
OperationId = "B349A6C4-1198-4B53-B9BE-85232E06F16E",
Tags = new[] {"Article"})
]
```
Personally, I don't like this approach. Another library ([FastEndpoints](https://github.com/dj-nitehawk/FastEndpoints)) has interesting alternative:
```cs
public class DeleteCustomerSummary : Summary
{
public DeleteCustomerSummary()
{
Summary = "Deleted a customer the system";
Description = "Deleted a customer the system";
Response(204, "The customer was deleted successfully");
Response(404, "The customer was not found in the system");
}
}
```
which produces this Swagger documentation:

IMO this is much cleaner, because I don't make my endpoints clogged up with comments.
Full project with this solution is [here](https://github.com/Elfocrash/clean-minimal-api/tree/master/Customers.Api/Summaries).
Is something like this possible with this library?
If not, I'm passing it to you as a feature request.
Contributor guide
Research direction
Start with the SwaggerOperation attribute above HandleAsync and compare it with the separate Summary approach shown from FastEndpoints. Review the linked Customers.Api/Summaries project for the proposed pattern. Done means establishing whether this library can support separate Swagger documentation classes and defining the required behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100