Warning

OpenAPI support for JSON:API is currently experimental. The API and the structure of the OpenAPI document may change in future versions.

OpenAPI

Exposing an OpenAPI document for your JSON:API endpoints enables to provide a documentation website and to generate typed client libraries in various languages.

The JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package provides OpenAPI support for JSON:API by integrating with Swashbuckle.

Getting started

1. Install the JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package:

   dotnet add package JsonApiDotNetCore.OpenApi.Swashbuckle --prerelease
   

2. Add the JSON:API support to your Program.cs file.

   builder.Services.AddJsonApi<AppDbContext>();
   
   // Configure Swashbuckle for JSON:API.
   builder.Services.AddOpenApiForJsonApi();
   
   var app = builder.Build();
   
   app.UseRouting();
   app.UseJsonApi();
   
   // Add the Swashbuckle middleware.
   app.UseSwagger();
   

By default, the OpenAPI document will be available at http://localhost:<port>/swagger/v1/swagger.json.

Customizing the Route Template

Because Swashbuckle doesn't properly implement the ASP.NET Options pattern, you must not use its documented way to change the route template:

// DO NOT USE THIS! INCOMPATIBLE WITH JSON:API!
app.UseSwagger(options => options.RouteTemplate = "api-docs/{documentName}/swagger.yaml");

Instead, always call UseSwagger() without parameters. To change the route template, use the code below:

builder.Services.Configure<SwaggerOptions>(options => options.RouteTemplate = "/api-docs/{documentName}/swagger.yaml");

If you want to inject dependencies to set the route template, use:

builder.Services.AddOptions<SwaggerOptions>().Configure<IServiceProvider>((options, serviceProvider) =>
{
    var webHostEnvironment = serviceProvider.GetRequiredService<IWebHostEnvironment>();
    string appName = webHostEnvironment.ApplicationName;
    options.RouteTemplate = $"/api-docs/{{documentName}}/{appName}-swagger.yaml";
});

Triple-slash comments

Documentation for JSON:API endpoints is provided out of the box, which shows in SwaggerUI and through IDE IntelliSense in auto-generated clients. To also get documentation for your resource classes and their properties, add the following to your project file. The NoWarn line is optional, which suppresses build warnings for undocumented types and members.

  <PropertyGroup>
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

You can combine this with the documentation that Swagger itself supports, by enabling it as described here. This adds documentation for additional types, such as triple-slash comments on enums used in your resource models.