Swashbuckle.OData

Extends Swashbuckle with OData v4 support!

Try it out!

Getting Started

Install the Swashbuckle.OData NuGet package:

Install-Package Swashbuckle.OData

In SwaggerConfig configure the custom provider:

c.CustomProvider(defaultProvider => new ODataSwaggerProvider(defaultProvider, c));

Custom Routes

The following snippet demonstrates how to configure a custom OData route such that it will appear in the Swagger UI:

// Let's say you map a custom OData route that doesn't follow the typical conventions
var customODataRoute = config.MapODataServiceRoute("CustomODataRoute", ODataRoutePrefix, GetModel(), batchHandler: null, pathHandler: new DefaultODataPathHandler(), routingConventions: myCustomConventions);

// Then describe your route to Swashbuckle.OData so that it will appear in the Swagger UI
config.AddCustomSwaggerRoute(customODataRoute, "/Customers({Id})/Orders")
    .Operation(HttpMethod.Post)
    // The name of the parameter as it appears in the path
    .PathParameter<int>("Id")
    // The name of the parameter as it appears in the controller action
    .BodyParameter<Order>("order");

The above route resolves to an OrderController action of:

[ResponseType(typeof(Order))]
public async Task<IHttpActionResult> Post([FromODataUri] int customerId, Order order)
{
  ...
}

OWIN

If your service is hosted using OWIN middleware, configure the custom provider as follows:

httpConfiguration
    .EnableSwagger(c =>
    {
        // Use "SingleApiVersion" to describe a single version API. Swagger 2.0 includes an "Info" object to
        // hold additional metadata for an API. Version and title are required but you can also provide
        // additional fields by chaining methods off SingleApiVersion.
        //
        c.SingleApiVersion("v1", "A title for your API");

        // Wrap the default SwaggerGenerator with additional behavior (e.g. caching) or provide an
        // alternative implementation for ISwaggerProvider with the CustomProvider option.
        //
        c.CustomProvider(defaultProvider => new ODataSwaggerProvider(defaultProvider, c, httpConfiguration));
    })
    .EnableSwaggerUi();

Development

You'll need:

Visual Studio 2015
Code Contracts

If you submit an enhancement or bug fix, please include a unit test similar to this that verifies the change. Let's shoot for 100% unit test coverage of the code base.

lakeba / Swashbuckle.OData