Produce OAS file at build time in example, referenced by client on disk (makes it easier to keep in sync during development)

Author: bkoelman

.gitattributes

@@ -1,5 +1,6 @@
 # When running OpenAPI tests, these committed files are downloaded and written to disk (so we'll know when something changes).
-# On Windows, these text files are auto-converted to crlf on fetch, while the written downloaded files use lf line endings.
+# On Windows, these text files are auto-converted to crlf on git fetch, while the written downloaded files use lf line endings.
 # Therefore, running the tests on Windows creates local changes. Staging them auto-converts back to crlf, which undoes the changes.
-# To avoid this annoyance, the next line opts out of the auto-conversion and forces to lf.
+# To avoid this annoyance, the next lines opt out of the auto-conversion and force to lf.
 swagger.g.json text eol=lf
+**/GeneratedSwagger/*.json text eol=lf

JsonApiDotNetCore.sln

@@ -69,6 +69,9 @@ 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}"
+	ProjectSection(ProjectDependencies) = postProject
+		{C916EBDA-3429-4FEA-AFB3-DF7CA32A8C6A} = {C916EBDA-3429-4FEA-AFB3-DF7CA32A8C6A}
+	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenApiClientTests", "test\OpenApiClientTests\OpenApiClientTests.csproj", "{77F98215-3085-422E-B99D-4C404C2114CF}"
 EndProject

package-versions.props

@@ -7,6 +7,7 @@
     <SwashbuckleFrozenVersion>6.5.0</SwashbuckleFrozenVersion>
 
     <!-- Non-published dependencies (these are safe to update, won't cause a breaking change) -->
+    <ApiDescriptionServerVersion>8.0.*</ApiDescriptionServerVersion>
     <BenchmarkDotNetVersion>0.13.*</BenchmarkDotNetVersion>
     <BlushingPenguinVersion>1.0.*</BlushingPenguinVersion>
     <BogusVersion>35.2.*</BogusVersion>

src/Examples/JsonApiDotNetCoreExampleClient/OpenAPIs/swagger.json renamed to src/Examples/JsonApiDotNetCoreExample/GeneratedSwagger/JsonApiDotNetCoreExample.json

@@ -6,7 +6,7 @@
   },
   "servers": [
     {
-      "url": "http://localhost:14140"
+      "url": "https://localhost:44340"
     }
   ],
   "paths": {

src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj

@@ -1,6 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
   <PropertyGroup>
     <TargetFrameworks>net8.0;net6.0</TargetFrameworks>
+    <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
+    <OpenApiDocumentsDirectory>GeneratedSwagger</OpenApiDocumentsDirectory>
   </PropertyGroup>
 
   <Import Project="..\..\..\package-versions.props" />
@@ -16,5 +18,6 @@
     <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="$(EntityFrameworkCoreVersion)" />
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="$(EntityFrameworkCoreVersion)" />
     <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="$(SwashbuckleVersion)" />
+    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="$(ApiDescriptionServerVersion)" PrivateAssets="all" />
   </ItemGroup>
 </Project>

src/Examples/JsonApiDotNetCoreExample/Program.cs

@@ -4,6 +4,7 @@
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Diagnostics;
 using JsonApiDotNetCore.OpenApi;
+using JsonApiDotNetCoreExample;
 using JsonApiDotNetCoreExample.Data;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Diagnostics;
@@ -16,7 +17,10 @@
 
 WebApplication app = CreateWebApplication(args);
 
-await CreateDatabaseAsync(app.Services);
+if (!IsGeneratingOpenApiDocumentAtBuildTime())
+{
+    await CreateDatabaseAsync(app.Services);
+}
 
 app.Run();
 
@@ -83,7 +87,7 @@ static void ConfigureServices(WebApplicationBuilder builder)
 
     using (CodeTimingSessionManager.Current.Measure("AddOpenApi()"))
     {
-        builder.Services.AddOpenApi(mvcCoreBuilder);
+        builder.Services.AddOpenApi(mvcCoreBuilder, options => options.DocumentFilter<SetOpenApiServerAtBuildTimeFilter>());
     }
 }
 
@@ -112,6 +116,11 @@ static void ConfigurePipeline(WebApplication app)
     app.MapControllers();
 }
 
+static bool IsGeneratingOpenApiDocumentAtBuildTime()
+{
+    return Environment.GetCommandLineArgs().Any(argument => argument.Contains("GetDocument.Insider"));
+}
+
 static async Task CreateDatabaseAsync(IServiceProvider serviceProvider)
 {
     await using AsyncServiceScope scope = serviceProvider.CreateAsyncScope();

src/Examples/JsonApiDotNetCoreExample/SetOpenApiServerAtBuildTimeFilter.cs

@@ -0,0 +1,25 @@
+using JetBrains.Annotations;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace JsonApiDotNetCoreExample;
+
+/// <summary>
+/// This is normally not needed. It ensures the server URL is added to the OpenAPI file during build.
+/// </summary>
+[UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)]
+internal sealed class SetOpenApiServerAtBuildTimeFilter(IHttpContextAccessor httpContextAccessor) : IDocumentFilter
+{
+    private readonly IHttpContextAccessor _httpContextAccessor = httpContextAccessor;
+
+    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
+    {
+        if (_httpContextAccessor.HttpContext == null)
+        {
+            swaggerDoc.Servers.Add(new OpenApiServer
+            {
+                Url = "https://localhost:44340"
+            });
+        }
+    }
+}

src/Examples/JsonApiDotNetCoreExampleClient/JsonApiDotNetCoreExampleClient.csproj

@@ -24,8 +24,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <OpenApiReference Include="OpenAPIs\swagger.json" CodeGenerator="NSwagCSharp" ClassName="ExampleApiClient">
-      <SourceUri>http://localhost:14140/swagger/v1/swagger.json</SourceUri>
+    <OpenApiReference Include="..\JsonApiDotNetCoreExample\GeneratedSwagger\JsonApiDotNetCoreExample.json" CodeGenerator="NSwagCSharp" ClassName="ExampleApiClient">
     </OpenApiReference>
   </ItemGroup>
 </Project>

src/JsonApiDotNetCore/Diagnostics/CodeTimingSessionManager.cs

@@ -31,7 +31,7 @@ public static ICodeTimer Current
     static CodeTimingSessionManager()
     {
 #if DEBUG
-        IsEnabled = !IsRunningInTest() && !IsRunningInBenchmark();
+        IsEnabled = !IsRunningInTest() && !IsRunningInBenchmark() && !IsGeneratingOpenApiDocumentAtBuildTime();
 #else
         IsEnabled = false;
 #endif
@@ -52,6 +52,12 @@ private static bool IsRunningInBenchmark()
         return Assembly.GetEntryAssembly()?.GetName().Name == "Benchmarks";
     }
 
+    // ReSharper disable once UnusedMember.Local
+    private static bool IsGeneratingOpenApiDocumentAtBuildTime()
+    {
+        return Environment.GetCommandLineArgs().Any(argument => argument.Contains("GetDocument.Insider"));
+    }
+
     private static void AssertHasActiveSession()
     {
         if (_session == null)