Summary

The web content provides a tutorial on how to generate a swagger.json file during the build process in .NET Core, .NET 5, and above using the Swashbuckle.AspNetCore.Cli package and tooling.

Abstract

Swagger, now known as the OpenAPI specification, is integral to defining Web APIs in .NET Core and beyond. The swagger.json file, which contains the complete API definition, can be automatically generated at build time, a feature particularly useful for API gateway configuration and DevOps pipeline tasks that validate the API definition before deployment. The article guides developers through setting up the necessary Swashbuckle ASP.NET Core packages and the Swashbuckle CLI tool, detailing how to create a tool manifest, install the correct CLI tool version, and configure the build process to produce the swagger.json file. It also addresses potential version mismatch errors and provides a solution for generating the Swagger file as part of the PostBuild event in the .csproj file.

Opinions

The author emphasizes the importance of having the swagger.json file available before the API is published online, especially for API gateway configuration and automated validation in DevOps pipelines.
The author suggests that using a Swagger file is a sign of quality and can be part of setting up a quality gate in the deployment process.
The author provides a cautionary note about the importance of using the correct version of the Swashbuckle CLI tool to match the .NET version being used, to avoid errors such as System.IO.FileLoadException.
The author highlights the future-proof aspect of the tutorial by indicating how to select the appropriate CLI tool version for different .NET versions, such as .NET 6 and .NET 7.
The author points out the convenience of having the swagger.json file generated on each build, particularly for its inclusion in build or release pipelines.

How to generate a swagger.json file on build in .NET core, .NET 5 and above

Swagger is a powerful tool to create Web APIs in .NET Core (and .NET 5). When your API is online there is a swagger.json file that contains the entire definition of your API. But did you know that there is a way to generate this swagger.json file on build time?

What is a swagger file?

A swagger file (nowadays known as a OpenAPI specification file) is a JSON file that contains the entire definition of your API. All endpoints, input- and response types are documented in it. If you are using the swagger nuget package in your project, this file is automatically created for you.

You can simply access this file by navigation to your API and adding /swagger.json and the end of the url.

Generate the file on build time

Now why would you need this swagger.json file on build time? If you are using an API gateway this file is used to configure the endpoints of your gateway. In this case you would need the file before your API is published online.

You could also add a Devops pipeline task that is going to validate the file for you. You could even set up a quality gate that requires a valid swagger file before your API can be deployed!

How to set it up

Note that for this tutorial I’m using .NET core 3.1 and I’m using the Swashbuckle.AspNetCore.Cli package.

Add the following packages to your project:

<PackageReference Include="Swashbuckle.AspNetCore" Version="5.0.0-rc5" />
<PackageReference Include="Swashbuckle.AspNetCore.Newtonsoft" Version="5.3.1" />
<PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="5.3.1" />

Next, create a tool manifest:

dotnet new tool-manifest

Install the Swashbuckle CLI tool and add it to the local manifest file:

dotnet tool install --version 5.3.1 Swashbuckle.AspNetCore.Cli

How future proof is this post?

If you are getting errors like this one:

1>Unhandled exception. System.IO.FileLoadException: Could not load file or assembly ‘System.Runtime, Version=7.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a’. The located assembly’s manifest definition does not match the assembly reference. (0x80131040)

1>File name: ‘System.Runtime, Version=7.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a’

error MSB3073: The command “dotnet swagger tofile — output swagger.json bin\Debug\….dll v1” exited with code -532462766.

It means you are using the wrong version of the CLI tool. Depending on the .NET version of your project, you might need to install a different version of the CLI.

When I wrote this post I was using some version of .NET core. The version of the CLI will vary based on what .NET version you are using. For example: if you are using .NET 6 use should use version 6.4.0. If you are using .NET 7 go for version 6.5.0.

The manifest file

All important information about the CLI tool is stored inside a manifest file.

If you take a look at the .config folder inside your repository you’ll notice that a new dotnet-tools.json file is created.

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "swashbuckle.aspnetcore.cli": {
      "version": "6.4.0",
      "commands": [
        "swagger"
      ]
    }
  }
}

The version will vary based on the version you installed.

Generating the swagger file

Now you can use a dotnet command to generate a swagger.json file. For example:

dotnet swagger tofile --output api.json bin/debug/netcoreapp3.1/xxx.yourApi.dll v1

Generating the file on build

If you want the file to be generated on each build, use a PostBuild target in your csproj file.

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
    <Exec Command="dotnet tool restore" />
    <Exec Command="dotnet swagger tofile --output swagger.json $(OutputPath)\$(AssemblyName).dll v1 " />
</Target>

Notice that v1 should match the name of the swagger document. If you didn’t change this in your startup you can leave it like it is.

And vwoala, the swagger.json file will now be included in your solution folder on each build. Useful if you need it in a build or release pipeline.