OWIN Middleware

• Package: NSwag.AspNet.Owin (.NET 4.5+)

The NuGet package provides extension methods to register the NSwag ASP.NET OWIN middlewares:

The middlewares are based on WebApiOpenApiDocumentGenerator - the old reflection based ASP.NET Core and ASP.NET generator. These middlewares will be deprecated eventually and will not receive many bug fixes and new features.

Swagger only:

• app.UseSwagger(assembly, configure): Registers the Swagger generator on a given route

Swagger and Swagger UI:

• app.UseSwaggerUi(assembly, configure): Registers the Swagger generator and Swagger UI v2.x on the given routes
• app.UseSwaggerUi(configure): Registers only the Swagger UI on the given route
• app.UseSwaggerUi3(configure): Registers the Swagger generator and Swagger UI v3.x on the given routes
• app.UseSwaggerReDoc(configure): Registers the Swagger generator and ReDoc on the given routes

The default routes to access the Swagger specification or Swagger UI:

• Swagger JSON: http://yourserver/swagger/v1/swagger.json
• Swagger UI: http://yourserver/swagger

Sample project

Integration

See also:

• OWIN Middleware in Global.asax

1. Install required NuGet packages

First, you need to install the required NSwag NuGet packages.

• NSwag.AspNet.Owin
• Microsoft.AspNet.WebApi.Owin
• Microsoft.Owin.Host.SystemWeb

2. Register the middleware

OWIN Startup Class Detection
Getting Started with OWIN and Katana

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
        var config = new HttpConfiguration();

        app.UseSwaggerUi(typeof(Startup).Assembly, settings => 
        {
            // configure settings here
            // settings.GeneratorSettings.*: Generator settings and extension points
            // settings.*: Routing and UI settings
        });
        app.UseWebApi(config);

        config.MapHttpAttributeRoutes();
        config.EnsureInitialized();
    }
}

Register only the Swagger generator (in this example: OWIN .NET 4.5+):

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
        var config = new HttpConfiguration();

        app.UseSwagger(typeof(Startup).Assembly, settings => 
        {
            // configure settings here
        });
        app.UseWebApi(config);

        config.MapHttpAttributeRoutes();
        config.EnsureInitialized();
    }
}

Configure the routing of the Swagger requests

There are two alternative ways to do this:

a) Pipe all request to the .NET pipeline

In the system.webServer tag, set runAllManagedModulesForAllRequests to true so that all requests are piped to ASP.NET:

<system.webServer>
    ...
    <modules runAllManagedModulesForAllRequests="true">
        ...

b) Pipe only the Swagger request to the specific middlewares

Important: The routes defined in the web.config and the UseSwagger/UseSwaggerUi methods must be the same:

<system.webServer>
    ...
    <handlers>
        ...
        <add name="NSwag" path="swagger" verb="*" 
             type="System.Web.Handlers.TransferRequestHandler" 
             preCondition="integratedMode,runtimeVersionv4.0" />

Customization

Usage with a custom default URL template

Important: This is not supported in the new API Explorer based generator.

When you are using the Web API to Swagger generator in an MVC web application, you may have to change the URL template to the one defined in the Startup.cs:

app.UseSwaggerUi(typeof(Startup).GetTypeInfo().Assembly, settings => 
{
    settings.GeneratorSettings.DefaultUrlTemplate = "{controller}/{action}/{id?}";
});

Post process the served Swagger specification

It is possible to transform the generated Swagger specification before it is served to the client:

app.UseSwagger(typeof(Startup).Assembly, settings =>
{
    settings.PostProcess = document => 
    {
        document.Info.Description = "My description"; 
    };
});

If you want to implement more reusable code, you can also implement Document Processors and Operation Processors.

For more info about the configuration settings, see AspNetCore Middleware.