Skip to content

CommandLine

Rico Suter edited this page May 14, 2018 · 95 revisions

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

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:

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"
      ],

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

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

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

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

nswag webapi2swagger /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 webapi2swagger /assembly:MyWebApiAssembly.dll 
                     /output:MyWebService.json
                     /InfoTitle:MyWebService
                     /InfoVersion:V1
                     /InfoDescription:"My web service"
                     /ServiceHost:my.host.net
                     /ServiceBasePath:"/api"
                     /ServiceSchemes:"http,https"

WebApiToSwaggerCommand.cs

Client Generators

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

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

SwaggerToTypeScriptClientCommand.cs

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

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

SwaggerToCSharpClientCommand.cs

Generate Swagger from .NET types

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

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

TypesToSwaggerCommand.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