Getting Started
This addin (unlike the normal Cake.NSwag
package) does not include NSwag in the addin, but acts as a wrapper over the NSwag command line interface (CLI). This means that while you do have to ensure NSwag is available in your environment, you can use this addin when running under .NET Core (unlike Cake.NSwag
).
Note
This addin shares 100% API compatibility with Cake.NSwag
so you should be able to simply swap the two in and out with no script changes required.
Installing NSwag's CLI
There are a variety of ways to install NSwag's CLI, including the NSwag.ConsoleCore
NuGet package or the nswag
package for npm
.
At this time, it's recommended to use the npm package as it natively supports both the .NET Framework and .NET Core versions of the NSwag CLI.
Warning
For this addin to work, you need to make sure one of nswag.exe
, nswag
, or nswag.cmd
is available in the PATH or the tools/
folder.
Including the addin
At the top of your script, just add the following to install the addin:
#addin nuget:?package=Cake.NSwag.Console
Usage
The addin exposes a single property alias NSwag
with all of the NSwag functionality available as methods.
The general process of using the alias is to get a source (a GenerationSource
implementation) and then output it to any number of generated targets. So, generating a Swagger spec from a Web API assembly is simply:
NSwag.FromWebApiAssembly("./web.assembly.dll").ToSwaggerSpecification("./swagger.json");
Or creating a TypeScript client from a JSON Schema:
NSwag.FromJsonSchema("./schema.json").ToTypeScriptClient("./client.ts");
The supported sources are:
- .NET assembly (
FromAssembly()
) - ASP.NET Web API assembly (
FromWebApiAssembly()
) - JSON Schema (
FromJsonSchema()
) - Swagger specification (
FromSwaggerSpecification()
)
Each source will have its own possible destinations that are covered in the documentation for those source types (see the Reference tab above).
Settings
Some targets allow for including a settings action to fine-tune the code generation process. This is highly specific to each generation target and you will need to check the documentation to confirm the available options. For more detail check the Settings page.