ardalis / ardalis/ApiEndpoints

Swagger documentation in separate class

Open
#184 2 comments 3 reactions 0 assignees View on GitHub
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:

![swagger-docs](https://user-images.githubusercontent.com/76855180/180302029-fdd8cf6d-9d0b-464b-b7d0-60f3311bd2d6.jpg)

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.