dotnet / dotnet/aspnetcore

OpenAPI metadata/annotations added by [Attributes] are overwritten by XML Comments

Open
#63,179 6 comments 0 reactions 0 assignees View on GitHub
area-mvc feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 6h
Merged PRs (30d)
290

Description

When customizing your OpenAPI document currently the Attributes are applied first and then the XML Comments transformer.

This is because the applying of attributes is happening within the `TransformJsonSchemaNode` and the XML Comments after that via a transformer.

In my humble opinion, `[Attributes]` should be leading as it is more _explicit_ than comments.

I see two ways to solve this:

1. We add checks if a schema attribute is already set in the Xml Comment transformers.
2. We move the transformations based on attributes to a SchemaTransformer.

For option 1 I see a lot of checks which need to be added in the transformer which would greatly decrease the maintainability of it.

For option 2 we need to be able to insert Transformers in a certain location because the XmlTransformer is added from the user-call-site, so that the order is `XmlTransformer` -> `AttributeTransformer` -> etc....
We could do this by exposing the transformers in an `IList` on the `OpenApiOptions`. This is unfortunatly an API change/addition.
Another benefit of Option 2 in my opinion is that that could enable disabling Validation Attributes for example, or other built-in transformations.

Tagging @captainsafia and @martincostello 😁

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.