Merge 8d50846 into e9c44c9

Author: bkoelman

Build.ps1

@@ -98,6 +98,15 @@ function CreateNuGetPackage {
     CheckLastExitCode
 }
 
+# In a PR the base branch needs to be fetched in order for regitlint to work.
+function FetchBaseBranchIfNotMaster() {
+    if ($env:APPVEYOR_PULL_REQUEST_NUMBER -And $env:APPVEYOR_REPO_BRANCH -ne "master") {
+        git fetch -q origin ${env:APPVEYOR_REPO_BRANCH}:${env:APPVEYOR_REPO_BRANCH}
+    }
+}
+
+FetchBaseBranchIfNotMaster
+
 dotnet tool restore
 CheckLastExitCode
 

Directory.Build.props

@@ -6,6 +6,10 @@
     <EFCorePostgresVersion>7.0.*</EFCorePostgresVersion>
     <MicrosoftCodeAnalysisVersion>4.4.*</MicrosoftCodeAnalysisVersion>
     <HumanizerVersion>2.14.1</HumanizerVersion>
+    <SwashbuckleVersion>6.4.*</SwashbuckleVersion>
+    <NSwagApiClientVersion>13.16.*</NSwagApiClientVersion>
+    <MicrosoftApiClientVersion>6.0.*</MicrosoftApiClientVersion>
+    <NewtonsoftJsonVersion>13.0.*</NewtonsoftJsonVersion>
     <JsonApiDotNetCoreVersionPrefix>5.1.3</JsonApiDotNetCoreVersionPrefix>
     <CodeAnalysisRuleSet>$(MSBuildThisFileDirectory)CodingGuidelines.ruleset</CodeAnalysisRuleSet>
     <WarningLevel>9999</WarningLevel>

JsonApiDotNetCore.sln

@@ -55,6 +55,16 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DatabasePerTenantExample",
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AnnotationTests", "test\AnnotationTests\AnnotationTests.csproj", "{24B0C12F-38CD-4245-8785-87BEFAD55B00}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "JsonApiDotNetCore.OpenApi", "src\JsonApiDotNetCore.OpenApi\JsonApiDotNetCore.OpenApi.csproj", "{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenApiTests", "test\OpenApiTests\OpenApiTests.csproj", "{B693DE14-BB28-496F-AB39-B4E674ABCA80}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "JsonApiDotNetCore.OpenApi.Client", "src\JsonApiDotNetCore.OpenApi.Client\JsonApiDotNetCore.OpenApi.Client.csproj", "{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "JsonApiDotNetCoreExampleClient", "src\Examples\JsonApiDotNetCoreExampleClient\JsonApiDotNetCoreExampleClient.csproj", "{7FC5DFA3-6F66-4FD8-820D-81E93856F252}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenApiClientTests", "test\OpenApiClientTests\OpenApiClientTests.csproj", "{77F98215-3085-422E-B99D-4C404C2114CF}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -281,6 +291,66 @@ Global
 		{24B0C12F-38CD-4245-8785-87BEFAD55B00}.Release|x64.Build.0 = Release|Any CPU
 		{24B0C12F-38CD-4245-8785-87BEFAD55B00}.Release|x86.ActiveCfg = Release|Any CPU
 		{24B0C12F-38CD-4245-8785-87BEFAD55B00}.Release|x86.Build.0 = Release|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Debug|x64.Build.0 = Debug|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Debug|x86.Build.0 = Debug|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Release|Any CPU.Build.0 = Release|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Release|x64.ActiveCfg = Release|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Release|x64.Build.0 = Release|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Release|x86.ActiveCfg = Release|Any CPU
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289}.Release|x86.Build.0 = Release|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Debug|x64.Build.0 = Debug|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Debug|x86.Build.0 = Debug|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Release|x64.ActiveCfg = Release|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Release|x64.Build.0 = Release|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Release|x86.ActiveCfg = Release|Any CPU
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80}.Release|x86.Build.0 = Release|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Debug|x64.Build.0 = Debug|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Debug|x86.Build.0 = Debug|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Release|x64.ActiveCfg = Release|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Release|x64.Build.0 = Release|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Release|x86.ActiveCfg = Release|Any CPU
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C}.Release|x86.Build.0 = Release|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Debug|x64.Build.0 = Debug|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Debug|x86.Build.0 = Debug|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Release|x64.ActiveCfg = Release|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Release|x64.Build.0 = Release|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Release|x86.ActiveCfg = Release|Any CPU
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252}.Release|x86.Build.0 = Release|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Debug|x64.Build.0 = Debug|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Debug|x86.Build.0 = Debug|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Release|Any CPU.Build.0 = Release|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Release|x64.ActiveCfg = Release|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Release|x64.Build.0 = Release|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Release|x86.ActiveCfg = Release|Any CPU
+		{77F98215-3085-422E-B99D-4C404C2114CF}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -304,6 +374,11 @@ Global
 		{83FF097C-C8C6-477B-9FAB-DF99B84978B5} = {7A2B7ADD-ECB5-4D00-AA6A-D45BD11C97CF}
 		{60334658-BE51-43B3-9C4D-F2BBF56C89CE} = {026FBC6C-AF76-4568-9B87-EC73457899FD}
 		{24B0C12F-38CD-4245-8785-87BEFAD55B00} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
+		{71287D6F-6C3B-44B4-9FCA-E78FE3F02289} = {7A2B7ADD-ECB5-4D00-AA6A-D45BD11C97CF}
+		{B693DE14-BB28-496F-AB39-B4E674ABCA80} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
+		{5ADAA902-5A75-4ECB-B4B4-03291D63CE9C} = {7A2B7ADD-ECB5-4D00-AA6A-D45BD11C97CF}
+		{7FC5DFA3-6F66-4FD8-820D-81E93856F252} = {026FBC6C-AF76-4568-9B87-EC73457899FD}
+		{77F98215-3085-422E-B99D-4C404C2114CF} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {A2421882-8F0A-4905-928F-B550B192F9A4}

JsonApiDotNetCore.sln.DotSettings

@@ -14,6 +14,9 @@ JsonApiDotNetCore.ArgumentGuard.NotNull($EXPR$);</s:String>
 	<s:Int64 x:Key="/Default/CodeEditing/NullCheckPatterns/PatternTypeNamesToPriority/=JetBrains_002EReSharper_002EFeature_002EServices_002ECSharp_002ENullChecking_002EThrowExpressionNullCheckPattern/@EntryIndexedValue">3000</s:Int64>
 	<s:Int64 x:Key="/Default/CodeEditing/NullCheckPatterns/PatternTypeNamesToPriority/=JetBrains_002EReSharper_002EFeature_002EServices_002ECSharp_002ENullChecking_002ETraceAssertPattern/@EntryIndexedValue">50</s:Int64>
 	<s:Boolean x:Key="/Default/CodeInspection/CodeAnnotations/PropagateAnnotations/@EntryValue">False</s:Boolean>
+	<s:Boolean x:Key="/Default/CodeInspection/ExcludedFiles/FileMasksToSkip/=swagger_002Ejson/@EntryIndexedValue">True</s:Boolean>
+	<s:String x:Key="/Default/CodeInspection/GeneratedCode/GeneratedFileMasks/=swagger_002Eg_002Ejson/@EntryIndexedValue">swagger.g.json</s:String>
+	<s:String x:Key="/Default/CodeInspection/GeneratedCode/GeneratedFileMasks/=swagger_002Ejson/@EntryIndexedValue">swagger.json</s:String>
 	<s:String x:Key="/Default/CodeInspection/Highlighting/AnalysisEnabled/@EntryValue">SOLUTION</s:String>
 	<s:Boolean x:Key="/Default/CodeInspection/Highlighting/IdentifierHighlightingEnabled/@EntryValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeInspection/Highlighting/IncludeWarningsInSwea/@EntryValue">True</s:Boolean>

appveyor.yml

@@ -15,6 +15,7 @@ environment:
 branches:
   only:
   - master
+  - openapi
   - develop
   - unstable
   - /release\/.+/
@@ -70,7 +71,7 @@ for:
         CD _site
         git add -A 2>&1
         git commit -m "Automated commit from cibuild" -q
-        if (-Not $env:APPVEYOR_PULL_REQUEST_TITLE) {
+        if (-Not $env:APPVEYOR_PULL_REQUEST_TITLE -And $env:APPVEYOR_REPO_BRANCH -eq 'master') {
             git push origin gh-pages -q
             echo "Documentation updated successfully."
         }

docs/usage/openapi-client.md

@@ -0,0 +1,139 @@
+# OpenAPI Client
+
+You can generate a JSON:API client in various programming languages from the [OpenAPI specification](https://swagger.io/specification/) file that JsonApiDotNetCore APIs provide.
+
+For C# .NET clients generated using [NSwag](https://github.com/RicoSuter/NSwag), we provide an additional package that introduces support for partial PATCH/POST requests. The issue here is that a property on a generated C# class being `null` could mean "set the value to `null` in the request" or "this is `null` because I never touched it".
+
+## Getting started
+
+### Visual Studio
+
+The easiest way to get started is by using the built-in capabilities of Visual Studio. The next steps describe how to generate a JSON:API client library and use our package.
+
+1.  In **Solution Explorer**, right-click your client project, select **Add** > **Service Reference** and choose **OpenAPI**.
+
+2.  On the next page, specify the OpenAPI URL to your JSON:API server, for example: `http://localhost:14140/swagger/v1/swagger.json`.
+    Optionally provide a class name and namespace and click **Finish**.
+    Visual Studio now downloads your swagger.json and updates your project file. This results in a pre-build step that generates the client code.
+
+    Tip: To later re-download swagger.json and regenerate the client code, right-click **Dependencies** > **Manage Connected Services** and click the **Refresh** icon.
+3.  Although not strictly required, we recommend to run package update now, which fixes some issues and removes the `Stream` parameter from generated calls.
+
+4.  Add some demo code that calls one of your JSON:API endpoints. For example:
+
+    ```c#
+    using var httpClient = new HttpClient();
+    var apiClient = new ExampleApiClient("http://localhost:14140", httpClient);
+
+    PersonCollectionResponseDocument getResponse =
+        await apiClient.GetPersonCollectionAsync();
+
+    foreach (PersonDataInResponse person in getResponse.Data)
+    {
+        Console.WriteLine($"Found user {person.Id} named " +
+            $"'{person.Attributes.FirstName} {person.Attributes.LastName}'.");
+    }
+    ```
+
+5.  Add our client package to your project:
+
+   ```
+   dotnet add package JsonApiDotNetCore.OpenApi.Client
+   ```
+
+6.  Add the following glue code to connect our package with your generated code. The code below assumes you specified `ExampleApiClient` as class name in step 2.
+
+    ```c#
+    using JsonApiDotNetCore.OpenApi.Client;
+    using Newtonsoft.Json;
+
+    partial class ExampleApiClient : JsonApiClient
+    {
+        partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings)
+        {
+            SetSerializerSettingsForJsonApi(settings);
+        }
+    }
+    ```
+
+7.  Extend your demo code to send a partial PATCH request with the help of our package:
+
+    ```c#
+    var patchRequest = new PersonPatchRequestDocument
+    {
+        Data = new PersonDataInPatchRequest
+        {
+            Id = "1",
+            Attributes = new PersonAttributesInPatchRequest
+            {
+                FirstName = "Jack"
+            }
+        }
+    };
+
+    // This line results in sending "lastName: null" instead of omitting it.
+    using (apiClient.RegisterAttributesForRequestDocument<PersonPatchRequestDocument,
+        PersonAttributesInPatchRequest>(patchRequest, person => person.LastName))
+    {
+        PersonPrimaryResponseDocument patchResponse =
+            await apiClient.PatchPersonAsync("1", patchRequest);
+
+        // The sent request looks like this:
+        // {
+        //   "data": {
+        //     "type": "people",
+        //     "id": "1",
+        //     "attributes": {
+        //       "firstName": "Jack",
+        //       "lastName": null
+        //     }
+        //   }
+        // }
+    }
+    ```
+
+### Other IDEs
+
+When using the command-line, you can try the [Microsoft.dotnet-openapi Global Tool](https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-5.0).
+
+Alternatively, the next section shows what to add to your client project file directly:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="3.0.0">
+    <PrivateAssets>all</PrivateAssets>
+    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+  </PackageReference>
+  <PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
+  <PackageReference Include="NSwag.ApiDescription.Client" Version="13.0.5">
+    <PrivateAssets>all</PrivateAssets>
+    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+  </PackageReference>
+</ItemGroup>
+
+<ItemGroup>
+  <OpenApiReference Include="OpenAPIs\swagger.json" CodeGenerator="NSwagCSharp" ClassName="ExampleApiClient">
+    <SourceUri>http://localhost:14140/swagger/v1/swagger.json</SourceUri>
+  </OpenApiReference>
+</ItemGroup>
+```
+
+From here, continue from step 3 in the list of steps for Visual Studio.
+
+## Configuration
+
+### NSwag
+
+The `OpenApiReference` element in the project file accepts an `Options` element to pass additional settings to the client generator,
+which are listed [here](https://github.com/RicoSuter/NSwag/blob/master/src/NSwag.Commands/Commands/CodeGeneration/OpenApiToCSharpClientCommand.cs).
+
+For example, the next section puts the generated code in a namespace, removes the `baseUrl` parameter and generates an interface (which is handy for dependency injection):
+
+```xml
+<OpenApiReference Include="swagger.json">
+  <Namespace>ExampleProject.GeneratedCode</Namespace>
+  <ClassName>SalesApiClient</ClassName>
+  <CodeGenerator>NSwagCSharp</CodeGenerator>
+  <Options>/UseBaseUrl:false /GenerateClientInterfaces:true</Options>
+</OpenApiReference>
+```

docs/usage/openapi.md

@@ -0,0 +1,43 @@
+# 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).
+
+
+## Getting started
+
+1.  Install the `JsonApiDotNetCore.OpenApi` NuGet package:
+
+    ```
+    dotnet add package JsonApiDotNetCore.OpenApi
+    ```
+
+2.  Add the integration in your `Program.cs` file.
+
+    ```c#
+    IMvcCoreBuilder mvcCoreBuilder = builder.Services.AddMvcCore();
+
+    builder.Services.AddJsonApi<AppDbContext>(mvcBuilder: mvcCoreBuilder);
+
+    // Configures Swashbuckle for JSON:API.
+    builder.Services.AddOpenApi(mvcCoreBuilder);
+
+    var app = builder.Build();
+
+    app.UseRouting();
+    app.UseJsonApi();
+
+    // Adds the Swashbuckle middleware.
+    app.UseSwagger();
+    ```
+
+By default, the OpenAPI specification will be available at `http://localhost:<port>/swagger/v1/swagger.json`.
+
+## Documentation
+
+Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), tooling for a generated documentation 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`.

docs/usage/toc.md

@@ -26,6 +26,9 @@
 
 # [Common Pitfalls](common-pitfalls.md)
 
+# [OpenAPI](openapi.md)
+## [Client](openapi-client.md)
+
 # Extensibility
 ## [Layer Overview](extensibility/layer-overview.md)
 ## [Resource Definitions](extensibility/resource-definitions.md)

src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj

@@ -7,10 +7,12 @@
     <ProjectReference Include="..\..\JsonApiDotNetCore\JsonApiDotNetCore.csproj" />
     <ProjectReference Include="..\..\JsonApiDotNetCore.SourceGenerators\JsonApiDotNetCore.SourceGenerators.csproj" OutputItemType="Analyzer"
       ReferenceOutputAssembly="false" />
+    <ProjectReference Include="..\..\JsonApiDotNetCore.OpenApi\JsonApiDotNetCore.OpenApi.csproj" />
   </ItemGroup>
 
   <ItemGroup>
     <PackageReference Include="Microsoft.EntityFrameworkCore" Version="$(EFCoreVersion)" />
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="$(EFCorePostgresVersion)" />
+    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="$(SwashbuckleVersion)" />
   </ItemGroup>
 </Project>

src/Examples/JsonApiDotNetCoreExample/Program.cs

@@ -2,6 +2,7 @@
 using System.Text.Json.Serialization;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Diagnostics;
+using JsonApiDotNetCore.OpenApi;
 using JsonApiDotNetCoreExample.Data;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.EntityFrameworkCore;
@@ -56,6 +57,8 @@ static void ConfigureServices(WebApplicationBuilder builder)
 #endif
     });
 
+    IMvcCoreBuilder mvcCoreBuilder = builder.Services.AddMvcCore();
+
     using (CodeTimingSessionManager.Current.Measure("AddJsonApi()"))
     {
         builder.Services.AddJsonApi<AppDbContext>(options =>
@@ -69,7 +72,12 @@ static void ConfigureServices(WebApplicationBuilder builder)
             options.IncludeExceptionStackTraceInErrors = true;
             options.IncludeRequestBodyInErrors = true;
 #endif
-        }, discovery => discovery.AddCurrentAssembly());
+        }, discovery => discovery.AddCurrentAssembly(), mvcBuilder: mvcCoreBuilder);
+    }
+
+    using (CodeTimingSessionManager.Current.Measure("AddOpenApi()"))
+    {
+        builder.Services.AddOpenApi(mvcCoreBuilder);
     }
 }
 
@@ -90,6 +98,9 @@ static void ConfigurePipeline(WebApplication webApplication)
         webApplication.UseJsonApi();
     }
 
+    webApplication.UseSwagger();
+    webApplication.UseSwaggerUI();
+
     webApplication.MapControllers();
 }