search

yahehe / Nancy.Swagger

Nancy plugin for generated API documentation in Swagger format.
MIT License
133 stars 60 forks source link

Xml Comments #105

Open sergiychernov opened 7 years ago

sergiychernov commented 7 years ago

@yahehe, @jnallard,

what do you guys think about extending Nancy.Swagger with ability to auto discover models (request/response) and/or using descriptions from XML documentation (summary... etc)?

Thanks

jnallard commented 7 years ago

Have you looked into Nancy.Swagger.Annotations? It's not XML, but it does allow you to specify your route descriptions directly onto your functions.

Other than that, if you wanted to create a new project (maybe Nancy.Swagger.XML), I wouldn't mind supporting it (or even helping). You would probably want to handle the code similarly to the Annotations project, which basically just creates a wrapper around Nancy.Swagger.

I doubt I'll spearhead this project though, as I think supporting Swagger 3 is more of a priority.

sergiychernov commented 7 years ago

Yeah, i looked at annotations. Thing is we would like to keep documentation for api in the same place where docs for code is... so i was wondering if there are any plans or maybe doubts? I am thinking about separate project, so will submit a PR once have something.

jnallard commented 7 years ago

I believe it's not a simple process to read the xml comments at runtime, because they are not available via reflection. https://stackoverflow.com/questions/15602606/programmatically-get-summary-comments-at-runtime (But feel free to research for yourself! If you can find a clean method, that would be cool)

You could always just document your functions using the annotations (unless the XML is supplying other benefits).

yahehe commented 7 years ago

I agree with Josh about the XML, totally fine having it part of Nancy.Swagger and helping maintain it but very low chance I'll write it. Auto-discovery of request/response models has come up before but I believe the old owner of this package had concerns about whether or not that was even possible with the way Nancy wires everything up. This may have changed by now, worth investigating