What is Swagger and does it relate to OData?

Question

I am familiar with the Microsoft stack. I am using OData for some of my restful services. Recently I came across Swagger for API documentation and I am trying to understand how it relates to OData. Both of them seem to be RESTful specifications. Which one is widely used?

Answer 1

Swagger is a specification for documenting APIs. By creating a swagger document for your API, you can pass it to an instance of Swagger UI, which renders the document in a neat, readable format and provides tooling to invoke your APIs. See the swagger.io website for further information.

OData is a specification for creating data services over http, it defines how a service should be constructed and what patterns it should follow. For example, the use of the $top directive to provide the first n results of a data set. OData is currently at version 4, but the v2 documentation has a very good overview.

Swashbuckle is a nuget package for the Microsoft stack that produces swagger documents for your API's automatically, based on inspecting the code and additional metadata you provide to shape the output document.

If you want Swashbuckle to automatically generate swagger documents for an OData API you are building, then you can use Swashbuckle.OData to provide this for you.

If you are using .NET Core, then it gets a little more complex, but a full example can be found at the .NET Core Swagger OData sample.

OpenAPI is a specification for describing API's; Swagger is an implementation of the OpenAPI standard. You can find more details here.

I hope this helps clear up any confusion.