OpenAPI metadata/annotations added by [Attributes] are overwritten by XML Comments
- 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
Assessment
This issue has not been assessed yet.