search

yahehe / Nancy.Swagger

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

Only describes parameters in functions that are specified #96

Closed jnallard closed 7 years ago

jnallard commented 7 years ago

Updates the swagger description to only include parameters that are actually annotated.

95

theHurc commented 7 years ago

Similar to the static parameter SwaggerAnnotationsConfig.ShowOnlyAnnotatedRoutes would it be appropriate to have a similar property that allows showing only annotated params? Could be useful for debugging....

jnallard commented 7 years ago

Working on a fix for the build.

@theHurc I could add that. But there is a difference between what is happening here and what was happening with the routes. The routes would show a lack of data (indicating undocumented routes), but these parameters are showing wrong data (indicating malformed route descriptions). For example, the POST /User route was showing User as a query parameter, which is just wrong.

So I see adding another config option as something that would mislead more than help debug.

A different solution I would be willing to do is to add your IgnoreInDocumentation or something - and add some automatic parameter documentation. That way User would be detected as a BodyParameter, because it's not a primitive. And you could still hide your async parameters.

theHurc commented 7 years ago

I see what you mean. Whatever you see as consistent with the rest of the code sounds good. I really don't know it that well.

jnallard commented 7 years ago

I'm still learning about it myself!

For now, I'm going to keep this quick solution. And I think I will address the automatic generation when we start working on Swagger 3.

theHurc commented 7 years ago

Excellent!

yahehe commented 7 years ago

Uuuuh I don't understand why the build is failing. I'll look into it tomorrow

jnallard commented 7 years ago

Appveyor works a little bit differently now, with different versions of the SDK installed.

I tried one of the solutions on this issue: https://github.com/appveyor/ci/issues/1377#issuecomment-287644271 { "sdk": { "version": "1.0.0-preview2-1-003177" } } This fixed the build issues on AppVeyor, but was annoying because then I'd have to have that specific version of the SDK on my dev machine.

I'm currently trying the approach of updating to Visual Studios 2017 tools.