Unable to Generate swagger.json file in project

[MatthijsVollenbroek]

Hi,

I am quite new to NSwag so maybe I am doing something wrong, but I want to generate a swagger.json file every time my project is build.

I have NSwag MSBuild Nuget package installed and added this to my ASP .NET Core project (.NET 8)

<Target Name="Generate OpenAPI Specification Document" AfterTargets="Build">
    <Exec Command="$(NSwagExe_Net80) aspnetcore2openapi /assembly:$(OutputPath)$(AssemblyName).dll /output:swagger.json" />
  </Target>

However, when buidling:

NConsole.UnusedArgumentException: Unrecognised arguments are present: [/assembly:bin\Debug\net8.0\CompanyService.Api.dll]
 at NConsole.CommandLineProcessor.ProcessSingleAsync(String[] args, Object input)
 at NConsole.CommandLineProcessor.ProcessAsync(String[] args, Object input)
 at NSwag.Commands.NSwagCommandProcessor.ProcessAsync(String[] args) in /_/src/NSwag.Commands/NSwagCommandProcessor.cs:line 62

Any ideas how to fix this?

[SebSepp016]

I have the same issue. Since net7 I used "webapi2swagger" to generate a "swagger.json" file. But "webapi2swagger" seemed to be removed in the latest version. So i tried to use "aspnetcore2openapi" but i ran into the same issue :-( Any news why "webapi2swagger" was removed and how to pass any paramter to the "aspnetcore2openapi"?

[olegd-superoffice]

@MatthijsVollenbroek Which version of NSwag you are using? If it is v14 preview then it is /assembly argument which is not supported any more (See #4524)

[RicoSuter]

The only supported way is the /project:MyProject.csproj which uses API explorer to retrieve APIs...

For everything else you'd want to implement your own CLI (aka console app) and use the NSwag packages to do whatever you want.

This change is because the only good way to use NSwag is via API explorer - the reflection based approach is not recommend, might be out-of-sync with the actual API...

[RicoSuter]

how to pass any paramter to the "aspnetcore2openapi"?

You essentially define the project with /project:MyProject.csproj and the /documentName:MyDocumentName. The document name can then be defined in

AddOpenApiDocument(document => document.DocumentName = "MyDocumentName");

in this callback you can also do whatever you want with the document, eg register an operation processor which filters out some operations etc.

[josteink]

The only supported way is the /project:MyProject.csproj which uses API explorer to retrieve APIs...

@RicoSuter : This change is troublesome and has many possibly non-obvious consequences:

• The first (and incorrect) assumption is that NSwag.exe will be able to successfully execute a build, not knowing if any build parameters might be required.
• The second is that this is a breaking change. Before one could reference NSwag.MSBuild in the project one wanted to generate documents for, using that in a post-build build-step. Now using it like that will cause a circular build dependency where trying to build a project, will cause nswag to trigger, which tries to build the same project, which will cause nswag to trigger... (and it will silently and inexplicably kill JetBrains Rider's build-system, until you reboot, but thats another story)
• A less obvious third issue is that building the project will also result in a nuget restore being performed, either it is needed or not. Depending on what package-sources one may have, they may be company internal and require special authentication and NSwag may not be executed in an authenticated context where these packages sources are available at all. This causes NSwag to fail, and also fail the build. (This also applies when the -nobuild:true parameter is supplied).
• Fourth, performance: Building an existing project again slows the overall build for no obvious gain.

These are 4 examples I can mention here which I know exists for real, because I've encountered them all. In a single project.

I kindly ask for the /assembly: parameter to be reintroduced. Pretty please? 😺

Adding this simple parameter will literally solve all the above problems. Until it is, I (and many others) wont be able to upgrade to version 14.

Edit: I've misread the stack trace. One of my problems is not related to dotnet restore requiring a valid Azure Identity, but that when trying to obtain the ServiceProvider of the referenced project, if the host-process uses Microsoft KeyVault, the CI worker will probably not be authorised against KeyVault, making the process fail.

Edit 2: KeyVault seems to get involved because in our Startup.cs we've declared IConfiguration as a DI dependency, and our configuration is resolved through KeyVault.

I'm not sure this is fixable at all, so for now, my current workaround is not running NSwag OpenAPI document generation at CI-time.

[Erithax]

Now using it like that will cause a circular build dependency

@josteink You can avoid the build cycle by passing /nobuild:true.

So your previous $(NSwagExe_Net80) aspnetcore2openapi /assembly:MyAsm.dll /output:swagger.json might now become $(NSwagExe_Net80) aspnetcore2openapi /project:MyProj.csproj /nobuild:true /output:swagger.json

As found on https://github.com/RicoSuter/NSwag/wiki/AspNetCoreOpenApiDocumentGenerator