Azure / Azure/azure-functions-openapi-extension
Is there a way to automatically include <summary> comments in the swagger output?
- Dominant language
- C#
- Stars
- 388
- Forks
- 202
- PR merge metrics
- No merged PRs in 30d
Description
It's a bit of a hassle having to maintain both the `///` comments and the `OpenApiOperation[]` annotation.
This is fair for the actual operations, but becomes more of a struggle with domain objects that are returned which may have lots of properties which are already documented properly in the documentation comments. Is it possible to somehow extract the `` text and have it used by default?
```
public class Person
{
///
/// Lorem ipsum dolor sit amet, consectetur adipiscing elit...
///
[OpenApiPropertyDescription("Lorem ipsum dolor sit amet, consectetur adipiscing elit...")]
public string? FirstName { get; set; }
///
/// Lorem ipsum dolor sit amet, consectetur adipiscing elit...
///
[OpenApiPropertyDescription("Lorem ipsum dolor sit amet, consectetur adipiscing elit...")]
public string? LastName { get; set; }
```
Contributor guide
Research direction
No file or test is named. Start by tracing the Swagger generation path that handles OpenApiPropertyDescription and inspect how XML documentation comments could be discovered for returned domain objects. Done means supported text is used in the OpenAPI output without requiring duplicate property-description annotations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, csharp, openapi
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100