Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save VincentH-Net/a950fb18363111ccac8e1fb64123647e to your computer and use it in GitHub Desktop.
Save VincentH-Net/a950fb18363111ccac8e1fb64123647e to your computer and use it in GitHub Desktop.
Generate OpenApi.json on build from ASP.NET 8 Minimal API

To generate OpenApi.json on build from an ASP.NET 8 Minimal API, follow these steps:

  1. In Visual Studio for Windows 17.7.0 or later, create a new ASP.NET Core API project

  2. Follow these instructions to install Swashbuckle.AspNetCore.Cli as a local dotnet tool in your project

  3. Add these NuGet packages (or later versions) to the project:

  <ItemGroup>
  	<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.0-preview.4.23260.4" />
  	<PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>
  1. Add this target to the .csproj file:
<!-- Generate openapi.json on build; see
     https://github.com/domaindrivendev/Swashbuckle.AspNetCore#using-the-tool-with-the-net-core-30-sdk-or-later -->
<Target Name="OpenAPI" AfterTargets="Build" Condition="$(Configuration)=='Debug'">
    <Exec Command="dotnet swagger tofile --output openapi.json $(TargetPath) v1" WorkingDirectory="$(TargetDir)" />
</Target>
  1. In Program.cs, add the OpenApi services:

    builder.Services.AddEndpointsApiExplorer()
                    .AddSwaggerGen();

    and append .WithOpenApi() to the MapGroup() statement:

    var todosApi = app.MapGroup("/todos").WithOpenApi();

    (optional) if you also want to generate the Swagger UI under the /swagger url, add:

    if (app.Environment.IsDevelopment()) _ = app.UseSwagger().UseSwaggerUI();
  2. Build the project; the build output will contain a line like:
    Swagger JSON/YAML successfully written to ...\bin\Debug\net8.0\openapi.json

@schnerring
Copy link

schnerring commented Sep 11, 2023

Does that snippet actually work for you on .NET 8?

I'm running into this issue: domaindrivendev/Swashbuckle.AspNetCore#1580

The JSON file is generated, but the minimal API endpoints (paths JSON property) are missing from it.

@VincentH-Net
Copy link
Author

@schnerring It worked when I wrote this gist, that is quite a few .NET 8 releases ago though and I did not try it since.
Did you try the workarounds 1 and 2 suggested in 1580?

@schnerring
Copy link

Yeah I've tried every workaround. I finally got it to work, but the whole Swagger generation feels brittle at the moment. Here is what I've found:

  • <URL>/swagger/v1/swagger.json is always generated correctly
  • <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild> doesn't work
  • dotnet swagger tofile is the only thing that works

Here are related issues for anyone who wants to follow the topic:

@VincentH-Net
Copy link
Author

VincentH-Net commented Sep 12, 2023

@schnerring glad you got it working
It took me some time to find out as well - that's why I included that doc link in the comment in the gist

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment