Set the describedby top-level link to point to the OpenAPI document URL

Author: bkoelman

docs/usage/openapi-client.md

@@ -1,8 +1,12 @@
 # OpenAPI clients
 
-After [enabling OpenAPI](~/usage/openapi.md), you can generate a JSON:API client for your API in various programming languages.
+After [enabling OpenAPI](~/usage/openapi.md), you can generate a typed JSON:API client for your API in various programming languages.
 
-The following generators are supported, though you may try others as well:
+> [!NOTE]
+> If you prefer a generic JSON:API client instead of a typed one, choose from the existing
+> [client libraries](https://jsonapi.org/implementations/#client-libraries).
+
+The following code generators are supported, though you may try others as well:
 - [NSwag](https://github.com/RicoSuter/NSwag): Produces clients for C# and TypeScript
 - [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/overview): Produces clients for C#, Go, Java, PHP, Python, Ruby, Swift and TypeScript
 
@@ -51,7 +55,8 @@ The following steps describe how to generate and use a JSON:API client in C#, us
 3.  Although not strictly required, we recommend running package update now, which fixes some issues.
 
     > [!WARNING]
-    > NSwag v14 is currently *incompatible* with JsonApiDotNetCore (tracked [here](https://github.com/RicoSuter/NSwag/issues/4662)). Stick with v13.x for the moment.
+    > NSwag v14 is currently *incompatible* with JsonApiDotNetCore (tracked [here](https://github.com/RicoSuter/NSwag/issues/4662)).
+    > Stick with v13.x for the moment.
 
 4.  Add our client package to your project:
 
@@ -141,8 +146,11 @@ The following steps describe how to generate and use a JSON:API client in C#, us
     ```
 
 > [!TIP]
-> The [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiNSwagClientExample) contains an enhanced version that uses `IHttpClientFactory` for [scalability](https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory) and [resiliency](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/http-requests#use-polly-based-handlers) and logs the HTTP requests and responses.
-> Additionally, the example shows how to write the swagger.json file to disk when building the server, which is imported from the client project. This keeps the server and client automatically in sync, which is handy when both are in the same solution.
+> The [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiNSwagClientExample) contains an enhanced version
+> that uses `IHttpClientFactory` for [scalability](https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory) and
+> [resiliency](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/http-requests#use-polly-based-handlers) and logs the HTTP requests and responses.
+> Additionally, the example shows how to write the swagger.json file to disk when building the server, which is imported from the client project.
+> This keeps the server and client automatically in sync, which is handy when both are in the same solution.
 
 ### Other IDEs
 
@@ -215,7 +223,8 @@ Likewise, you can enable nullable reference types by adding `/GenerateNullableRe
 The available command-line switches for Kiota are described [here](https://learn.microsoft.com/en-us/openapi/kiota/using#client-generation).
 
 At the time of writing, Kiota provides [no official integration](https://github.com/microsoft/kiota/issues/3005) with MSBuild.
-Our [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiKiotaClientExample) takes a stab at it, although it has glitches. If you're an MSBuild expert, please help out!
+Our [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiKiotaClientExample) takes a stab at it,
+although it has glitches. If you're an MSBuild expert, please help out!
 
 ```xml
 <Target Name="KiotaRunTool" BeforeTargets="BeforeCompile;CoreCompile" Condition="$(DesignTimeBuild) != true And $(BuildingProject) == true">

docs/usage/openapi-documentation.md

@@ -0,0 +1,20 @@
+# OpenAPI documentation
+
+After [enabling OpenAPI](~/usage/openapi.md), you can expose a documentation website with SwaggerUI or Redoc.
+
+### SwaggerUI
+
+Swashbuckle ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), which enables to visualize and interact with the JSON:API endpoints through a web page.
+This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
+
+```c#
+app.UseSwaggerUI();
+```
+
+By default, SwaggerUI will be available at `http://localhost:<port>/swagger`.
+
+### Redoc
+
+[Redoc](https://github.com/Redocly/redoc) is another popular tool that generates a documentation website from an OpenAPI document.
+It lists the endpoints and their schemas, but doesn't provide the ability to execute requests.
+The `Swashbuckle.AspNetCore.ReDoc` NuGet package provides integration with Swashbuckle.

docs/usage/openapi.md

@@ -1,9 +1,11 @@
 # OpenAPI
 
-JsonApiDotNetCore provides an extension package that enables you to produce an [OpenAPI specification](https://swagger.io/specification/) for your JSON:API endpoints.
-This can be used to generate a [documentation website](https://swagger.io/tools/swagger-ui/) or to generate [client libraries](https://openapi-generator.tech/docs/generators/) in various languages.
-The package provides an integration with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
+Exposing an [OpenAPI document](https://swagger.io/specification/) for your JSON:API endpoints enables to provide a
+[documentation website](https://swagger.io/tools/swagger-ui/) and to generate typed
+[client libraries](https://openapi-generator.tech/docs/generators/) in various languages.
 
+The [JsonApiDotNetCore.OpenApi](https://github.com/json-api-dotnet/JsonApiDotNetCore/pkgs/nuget/JsonApiDotNetCore.OpenApi) NuGet package
+provides OpenAPI support for JSON:API by integrating with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
 
 ## Getting started
 
@@ -13,7 +15,11 @@ The package provides an integration with [Swashbuckle](https://github.com/domain
     dotnet add package JsonApiDotNetCore.OpenApi
     ```
 
-2.  Add the integration in your `Program.cs` file.
+    > [!NOTE]
+    > Because this package is still experimental, it's not yet available on NuGet.
+    > Use the steps [here](https://github.com/json-api-dotnet/JsonApiDotNetCore?tab=readme-ov-file#trying-out-the-latest-build) to install.
+
+2.  Add the JSON:API support to your `Program.cs` file.
 
     ```c#
     builder.Services.AddJsonApi<AppDbContext>();
@@ -30,22 +36,37 @@ The package provides an integration with [Swashbuckle](https://github.com/domain
     app.UseSwagger();
     ```
 
-By default, the OpenAPI specification will be available at `http://localhost:<port>/swagger/v1/swagger.json`.
+By default, the OpenAPI document will be available at `http://localhost:<port>/swagger/v1/swagger.json`.
+
+### Customizing the Route Template
 
-## Documentation
+Because Swashbuckle doesn't properly implement the ASP.NET Options pattern, you must *not* use its
+[documented way](https://github.com/domaindrivendev/Swashbuckle.AspNetCore?tab=readme-ov-file#change-the-path-for-swagger-json-endpoints)
+to change the route template:
 
-### SwaggerUI
+```c#
+// DO NOT USE THIS! INCOMPATIBLE WITH JSON:API!
+app.UseSwagger(options => options.RouteTemplate = "api-docs/{documentName}/swagger.yaml");
+```
 
-Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), which enables to visualize and interact with the API endpoints through a web page.
-This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
+Instead, always call `UseSwagger()` *without parameters*. To change the route template, use the code below:
 
 ```c#
-app.UseSwaggerUI();
+builder.Services.Configure<SwaggerOptions>(options => options.RouteTemplate = "api-docs/{documentName}/swagger.yaml");
 ```
 
-By default, SwaggerUI will be available at `http://localhost:<port>/swagger`.
+If you want to inject dependencies to set the route template, use:
+
+```c#
+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
+## 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.
@@ -58,5 +79,6 @@ The `NoWarn` line is optional, which suppresses build warnings for undocumented
   </PropertyGroup>
 ```
 
-You can combine this with the documentation that Swagger itself supports, by enabling it as described [here](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments).
+You can combine this with the documentation that Swagger itself supports, by enabling it as described
+[here](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments).
 This adds documentation for additional types, such as triple-slash comments on enums used in your resource models.

docs/usage/toc.md

@@ -26,6 +26,7 @@
 # [Common Pitfalls](common-pitfalls.md)
 
 # [OpenAPI](openapi.md)
+## [Documentation](openapi-documentation.md)
 ## [Clients](openapi-client.md)
 
 # Extensibility

src/JsonApiDotNetCore.OpenApi/OpenApiDescriptionLinkProvider.cs

@@ -0,0 +1,41 @@
+using JsonApiDotNetCore.Serialization.Response;
+using Microsoft.Extensions.Options;
+using Swashbuckle.AspNetCore.Swagger;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace JsonApiDotNetCore.OpenApi;
+
+/// <summary>
+/// Provides the OpenAPI URL for the "describedby" link in https://jsonapi.org/format/#document-top-level.
+/// </summary>
+internal sealed class OpenApiDescriptionLinkProvider : IDocumentDescriptionLinkProvider
+{
+    private readonly IOptionsMonitor<SwaggerGeneratorOptions> _swaggerGeneratorOptionsMonitor;
+    private readonly IOptionsMonitor<SwaggerOptions> _swaggerOptionsMonitor;
+
+    public OpenApiDescriptionLinkProvider(IOptionsMonitor<SwaggerGeneratorOptions> swaggerGeneratorOptionsMonitor,
+        IOptionsMonitor<SwaggerOptions> swaggerOptionsMonitor)
+    {
+        ArgumentGuard.NotNull(swaggerGeneratorOptionsMonitor);
+        ArgumentGuard.NotNull(swaggerOptionsMonitor);
+
+        _swaggerGeneratorOptionsMonitor = swaggerGeneratorOptionsMonitor;
+        _swaggerOptionsMonitor = swaggerOptionsMonitor;
+    }
+
+    /// <inheritdoc />
+    public string? GetUrl()
+    {
+        SwaggerGeneratorOptions swaggerGeneratorOptions = _swaggerGeneratorOptionsMonitor.CurrentValue;
+
+        if (swaggerGeneratorOptions.SwaggerDocs.Count > 0)
+        {
+            string latestVersionDocumentName = swaggerGeneratorOptions.SwaggerDocs.Last().Key;
+
+            SwaggerOptions swaggerOptions = _swaggerOptionsMonitor.CurrentValue;
+            return swaggerOptions.RouteTemplate.Replace("{documentName}", latestVersionDocumentName).Replace("{json|yaml}", "json");
+        }
+
+        return null;
+    }
+}

src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs

@@ -1,5 +1,6 @@
 using JsonApiDotNetCore.OpenApi.JsonApiMetadata;
 using JsonApiDotNetCore.OpenApi.SwaggerComponents;
+using JsonApiDotNetCore.Serialization.Response;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.Extensions.DependencyInjection;
@@ -75,6 +76,7 @@ private static void AddSwaggerGenerator(IServiceCollection services)
         AddSchemaGenerators(services);
 
         services.TryAddSingleton<RelationshipTypeFactory>();
+        services.AddSingleton<IDocumentDescriptionLinkProvider, OpenApiDescriptionLinkProvider>();
 
         services.AddSwaggerGen();
         services.AddSingleton<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerGenOptions>();

test/OpenApiKiotaEndToEndTests/QueryStrings/FilterTests.cs

@@ -139,6 +139,8 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
             response.Data.ElementAt(0).Id.Should().Be(node.Children.ElementAt(1).StringId);
             response.Meta.ShouldNotBeNull();
             response.Meta.AdditionalData.ShouldContainKey("total").With(total => total.Should().Be(1));
+            response.Links.ShouldNotBeNull();
+            response.Links.Describedby.Should().Be("swagger/v1/swagger.json");
         }
     }
 
@@ -162,6 +164,8 @@ public async Task Cannot_use_empty_filter()
             // Assert
             ErrorResponseDocument exception = (await action.Should().ThrowExactlyAsync<ErrorResponseDocument>()).Which;
             exception.ResponseStatusCode.Should().Be((int)HttpStatusCode.BadRequest);
+            exception.Links.ShouldNotBeNull();
+            exception.Links.Describedby.Should().Be("swagger/v1/swagger.json");
             exception.Errors.ShouldHaveCount(1);
 
             ErrorObject error = exception.Errors[0];

test/OpenApiNSwagClientTests/LegacyClient/ResponseTests.cs

@@ -203,7 +203,8 @@ public async Task Getting_unknown_resource_translates_error_response()
         const string responseBody = $$"""
             {
               "links": {
-                "self": "http://localhost/api/flights/ZvuH1"
+                "self": "http://localhost/api/flights/ZvuH1",
+                "describedby": "swagger/v1/swagger.json"
               },
               "errors": [
                 {
@@ -225,6 +226,9 @@ public async Task Getting_unknown_resource_translates_error_response()
         // Assert
         ApiException<ErrorResponseDocument> exception = (await action.Should().ThrowExactlyAsync<ApiException<ErrorResponseDocument>>()).Which;
         exception.StatusCode.Should().Be((int)HttpStatusCode.NotFound);
+        exception.Result.Links.ShouldNotBeNull();
+        exception.Result.Links.Self.Should().Be("http://localhost/api/flights/ZvuH1");
+        exception.Result.Links.Describedby.Should().Be("swagger/v1/swagger.json");
         exception.Result.Errors.ShouldHaveCount(1);
 
         ErrorObject? error = exception.Result.Errors.ElementAt(0);

test/OpenApiNSwagEndToEndTests/QueryStrings/FilterTests.cs

@@ -127,6 +127,8 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
         response.Data.ElementAt(0).Id.Should().Be(node.Children.ElementAt(1).StringId);
         response.Meta.ShouldNotBeNull();
         response.Meta.ShouldContainKey("total").With(total => total.Should().Be(1));
+        response.Links.ShouldNotBeNull();
+        response.Links.Describedby.Should().Be("swagger/v1/swagger.json");
     }
 
     [Fact]
@@ -148,6 +150,8 @@ public async Task Cannot_use_empty_filter()
         ApiException<ErrorResponseDocument> exception = (await action.Should().ThrowExactlyAsync<ApiException<ErrorResponseDocument>>()).Which;
         exception.StatusCode.Should().Be((int)HttpStatusCode.BadRequest);
         exception.Message.Should().Be("HTTP 400: The query string is invalid.");
+        exception.Result.Links.ShouldNotBeNull();
+        exception.Result.Links.Describedby.Should().Be("swagger/v1/swagger.json");
         exception.Result.Errors.ShouldHaveCount(1);
 
         ErrorObject error = exception.Result.Errors.ElementAt(0);