Update docs with more clarity around which XML comments tags are and aren't support

domaindrivendev / Swashbuckle.AspNetCore

Swagger tools for documenting API's built on ASP.NET Core

MIT License

5.24k stars 1.31k forks source link

Update docs with more clarity around which XML comments tags are and aren't support #1014

Open effyteva opened 5 years ago

effyteva commented 5 years ago

Hi guys,

Currently the XmlCommentsSchemaFilter doesn't work follow the same logic as XmlCommentsOperationFilter. Properties doesn't expose their "remarks" XML attribute tags. The remarks could be easily added into the schema.Description property, by combining the Summary and the Remarks together. This should allow for better documentation...

Thanks, Effy

Leon99 commented 5 years ago

...plus, it's not clear that <remarks> is supported for operations but not for model properties. At the very least, worth adding to readme?

domaindrivendev commented 3 years ago

I want to maintain a 1:1 mapping between XML tag and Swagger field, and avoid getting into combining the various XML tags, and so won't be adding this feature.

But, I agree the docs should be updated to be more clear about what is and isn't supported

304NotModified commented 2 years ago

Where could we change these docs? I like to fix and close this