Using the Swashbuckle library to create the swagger.json file
Generally, if you have ASP.NET Core Web API service you have a swagger GUI which shows info about your API methods. Of course, you can copy and paste the swagger.json of your API from that GUI. But sometimes you might need that swagger.json file inside a build pipeline. And it’s quite likely that you don’t want to put that file into your repository. In such a situation, you must find a way to generate that swagger.json file while the service is not running. Here the Swashbuckle Library can help you out.
The Swashbuckle library can be used as follows:
dotnet swagger tofile --output swagger.json MyService.API\bin\Debug\net6.0\MyService.API.dll v1
This command can also be included in your service .csproj file so that it is always executed after the service is published:
MyService.API.csproj:
...
<Target Name="GenerateSwaggerJsonFile" AfterTargets="Publish" Condition="$(Configuration)=='Release'">
<Message Text="generating the swagger.json file" Importance="high" />
<Exec EnvironmentVariables="ASPNETCORE_ENVIRONMENT=SwaggerFileGeneration;DOTNET_ENVIRONMENT=SwaggerFileGeneration" Command="dotnet swagger tofile --output ./swagger.json $(OutputPath)$(AssemblyName).dll v1" />
</Target>
...If we use the “dotnet swagger” command configured like shown above in .csproj file, the command would try to load the appsettings.SwaggerFileGeneration.json file instead of appsettings.Debug.json or appsettings.json file.
But you have to be aware that running the “dotnet swagger” will run parts of your application because it uses reflection to execute parts of the code. So you have to make sure that you can deal with any dependencies that might cause problems if parts of your application are executed.
To deal with this problem you can, for example, use the name of the application that has launched the code to do something else in your code if you have an external dependency that cannot work if the affected part of the application is executed using reflection by the “dotnet swagger” command. Here is an example of how to do that:
using Microsoft.Extensions.PlatformAbstractions;
. . .
if (PlatformServices.Default.Application.ApplicationName == "dotnet-swagger")
{
// Do something else instead of using external dependencies that cannot work in this context
}
. . .Another way to do the same thing would be to use the ASPNETCORE_ENVIRONMENT variable:
. . .
if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "SwaggerFileGeneration")
{
// Do something else instead of using external dependencies that cannot work in this context
}
. . .You also have to be aware that appsettings.json mechanism might not work in “dotnet swagger” context (Swashbuckle.AspNetCore.Cli). You can read more about this here:
Relationship between ASPNETCORE_ENVIRONMENT parameter and appsettings.x.json file
There is a relationship between the value (SwaggerFileGeneration) of the parameter ASPNETCORE_ENVIRONMENT in .csproj file and the corresponding part in the name of the appsettings.SwaggerFileGeneration.json file that is generated for a .csproj file configured using the ASPNETCORE_ENVIRONMENT parameter.
Removing status code 200 from Swagger file
By default, Swashbuckle adds status code 200 to the OpenAPI definition for every Web API method. But you can remove it using the [ProducesResponseType(StatusCodes.Status300MultipleChoices)] attribute. So in the following example, Swashbuckls would add status code 200 as a possible return status code in the Swagger file if this attribute was not there:
[HttpPost]
[ProducesResponseType(StatusCodes.Status300MultipleChoices)]
public async Task<IActionResult> SomeApiMethod(ClassX param)
{
...
}