search

joukevandermaas / saule

JSON API library for ASP.Net Web API 2.
https://joukevandermaas.github.io/saule
MIT License
76 stars 37 forks source link

Autogenerated Swashbuckle swagger documentation is incorrect #140

Closed bjornharrtell closed 7 years ago

bjornharrtell commented 7 years ago

As Swashbuckle will try to guess the schema for the plain entity types it will not expose a swagger documentation for the actual JSON API as exposed by Saule.

It would be nice to somehow make Swashbuckle understand that what is really input/output in the REST API is ApiResources, without customizing the Swashbuckle Config.

bjornharrtell commented 7 years ago

While it would be good to auto wire this somehow, at least it seems possible to use SwaggerResponseAttribute and SwaggerSchemaFilterAttribute to correctly instruct Swashbuckle.

bjornharrtell commented 7 years ago

I've had success implementing special purpose IDocumentFilter and IOperationFilter which could be packaged into a ISwaggerProvider for a more or less generic solution to auto wire support for JSON API with Swashbuckle. The latter would require further non-trivial work.

A caveat is that it's not possible to ref/extend to the JSON API JSON Schema as Swagger 2.0 does not support enough of JSON Schema. This seems to be changing in Swagger 3.0 but it's far off to be generally available. I still think Swagger 2.0 can be useful as documentation for JSON API, you just have to leave out some details which can be referred to the actual JSON API spec at relevant places.

joukevandermaas commented 7 years ago

I think this was solved with #142.