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:
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):