CommandLine

• Issues: All open issues

Important for .NET Core: Assembly loading#net-core

To use the command line tool nswag.exe (.NET 4.6+) / dotnet-nswag.dll (.NET Core), choose one of the following methods:

• NSwag NPM Module: Bindings for the .NET 4.6+ and .NET Core command line tools (depending on installed framework/OS platform)
• Download latest NSwagStudio MSI installer or install package NSwagStudio via Chocolatey: After installing the application, the path to the nswag.exe binary is registered in the PATH variable so that the tool can be used in the Windows command line.
• Download the latest command line tools: Extract the ZIP archive and use the nswag.exe binary in the Windows command line.
• NSwag.MSBuild NuGet package

To see all available commands and parameters, run the command line application "nswag.exe" without parameters and enter "help" as command. All "input" parameters accept file paths, URLs and JSON data.

Commands:

• run: Executes an nswag.json config file (recommended)
• aspnetcore2openapi: AspNetCoreToOpenApiCommand
• webapi2openapi: WebApiToOpenApiCommand (should not be used for ASP.NET Core projects)
• types2openapi: TypesToOpenApiCommand
• openapi2csclient: CSharpClientCommand
• openapi2cscontroller: CSharpControllerCommand
• openapi2tsclient: TypeScriptClientCommand

Execute .nswag configuration document

An .nswag configuration document contains the instructions to generate/read a Swagger specification and generate code from it. The configuration document can be created with the NSwagStudio or manually by editing its JSON contents. To create a new nswag.json document in the current directory, use the new command:

nswag new

You can execute an .nswag configuration document by using the run command:

nswag run MySwaggerConfig.nswag

To run all .nswag configuration documents (*.nswag and nswag.json) in the current directory use the run command without parameters:

nswag run

Keep in mind that code generators are only executed when the output path is set.

Document variables

You can use variables in the document and replace them via command line. Just define use a variable in the document:

{
  "defaultVariables": "Configuration=Debug",
  "swaggerGenerator": {
    "webApiToSwagger": {
      "assemblyPaths": [
        "bin/$(Configuration)/netcoreapp2.0/Apiverse.Web.dll"
      ],

You can define multiple variables by seperate key value pairs with a comma.

nswag run /variables:Configuration=Release,SecondVariable=true

As you can see, you can define the default variables with the defaultVariables properties and use it with $(MyVariable).

You can now replace the parameter via command line

nswag run /variables:Configuration=Release

With the NSwag.MSBuild package you can pass, the current Configuration to the document:

<Exec Command="$(NSwagExe_Core20) run nswag.json /variables:Configuration=$(Configuration)" />

Swagger Generators

For ASP.NET Core apps, see AspNetCoreToOpenApiCommand

Deprecated

The following commands should not be used with ASP.NET Core

To generate a Swagger/OpenAPI specification from a Web API controller in a .NET assembly, see WebApiOpenApiDocumentGenerator for more information:

nswag webapi2openapi /assembly:MyWebApiAssembly.dll 
                     /controller:MyNamespace.MyController 
                     /output:MyWebService.json

To generate a single Swagger/OpenAPI specification for all controllers in the assembly, just call the command without the controller parameter:

nswag webapi2openapi /assembly:MyWebApiAssembly.dll 
                     /output:MyWebService.json

The assembly parameter accepts multiple assemblies separated with a comma, e.g. /assembly:a1.dll,a2.dll.

To populate the info (title, description, version), host, basepath, and schemes data in your output file, use the following command line parameters:

nswag webapi2openapi /assembly:MyWebApiAssembly.dll 
                     /output:MyWebService.json
                     /InfoTitle:MyWebService
                     /InfoVersion:V1
                     /InfoDescription:"My web service"
                     /ServiceHost:my.host.net
                     /ServiceBasePath:"/api"
                     /ServiceSchemes:"http,https"

WebApiToOpenApiCommand.cs

Client Generators

Generate TypeScript client code from a Swagger specification, see TypeScriptClientGenerator for more information:

nswag openapi2tsclient /input:MyWebService.json 
                       /output:MyModule.ts

TypeScriptClientCommand.cs

Generate C# client code from a Swagger specification, see CSharpClientGenerator:

nswag openapi2csclient /input:MyWebService.json 
                       /classname:MyServiceClient 
                       /namespace:MyNamespace
                       /output:MyServiceClient.cs

CSharpClientCommand.cs

Generate Swagger from .NET types

Generate a Swagger/OpenAPI specification describing only the given .NET types:

nswag types2swagger /assembly:MyAssembly.dll
                    /classnames:MyNamespace.Person,MyNamespace.Car 
                    /output:MySwagger.json

TypesToOpenApiCommand.cs

JSON Schema converters

Generate C# classes from a JSON Schema:

nswag jsonschema2csclient /input:JsonSchema.json 
                          /output:MyClasses.cs

JsonSchemaToCSharpCommand.cs

Generate TypeScript interfaces from a JSON Schema:

nswag jsonschema2tsclient /input:JsonSchema.json 
                          /output:MyInterfaces.ts

JsonSchemaToTypeScriptCommand.cs

Appendix: How to use UseDocumentProvider

Run a customized build and select the assembly in NSwagStudio, create an nswag.json and execute it via CLI (nswag run nswag.json):