How to document OData endpoints (swagger, swashbuckle, other)?

Question

What is the best way of documenting OData endpoints? Is there a way to use Swashbuckle for it?

Answer 1

Yes, try Swashbuckle.OData. It adds Swashbuckle support for ODataControllers.

See it in action here: http://swashbuckleodata.azurewebsites.net/swagger

Answer 2

Yes, we are trying to support it like yaml -> Swagger, yaml -> csdl ..

But it will need time to implementation, you can see a prototype and track there https://github.com/OData/model-first

Answer 3

I actually got something working for this using the IDocumentFilter function within Swashbuckle. I answered a similar question on the GitHub repo for Swashbuckle. Check out my response here (it's either at bottom or toward bottom):

https://github.com/domaindrivendev/Swashbuckle/issues/149

I've posted an example of a working IDocumentFilter implementation that you could leverage to get your OData endpoint set up in the Swagger ui.

Answer 4

The easiest way to do that I found is to convert OData definition to Open API spec using https://github.com/oasis-tcs/odata-openapi

Then import the spec document into swagger is very easy.

Answer 5

Asp NET and Asp NET Core Api Versioning

You can use Api Versioning (as it extends ApiExplorer with Odata information) for both WebApi and AspNetCore.

There are samples available for both:

• WebApi
• Asp Net Core

This sample how it integrates well with Swashbuckle/Swagger ui.