OpenAPI

OpenAPI - NSwag

Introduction

Installation

Use Nuget to install

  • NSwag.AspNetCore

Installation - NSwagStudio

Open a command prompt with elevated security.

Execute the following command

1
choco install nswagstudio

This will the NSwagStudio application on your computer.

Program.CS modifications

Add 

1
builder.Services.AddOpenApiDocument();

After the AddControllers statement

NSwagStudio

Execute your microservice project.

1
https://localhost:7245/swagger/index.html

Actually you want to see the json code itself

1
https://localhost:7245/swagger/v1/swagger.json

Now Execute NSwagStudio from the start prompt.
Add the url to the Json to ‘Specification URL:’ and press the Create local Copy button.

Click the TypeScript Client in the Outputs area, and then click Generate Outputs

Your code will be in the TypeScript Client tab, the Output subtab.

You can adjust this output by changing settings on the Settings subtab.

The Application is capable of generating a TypeScript Client, a CSharp Client, and a CSharp Controller

  • TypeScript - Generates the layer you will use to communicate with your API.
  • CSharp Client - I have no plans to use this. I create typeScript and Javascript
  • CSharp Controller - I will never use this as I created my openAPI in the microservice I was developing.

Opinions

  • Today is 5/23/2024, I installed the latest version of NSwag v14.0.7.0. It supports generating typescript 4.3. When I goto https://www.typescriptlang.org/ I see that the current version of typescript is 5.4. So it’s behind, but not very far behind.
  • The code generated includes JSDoc in the code.
  • The code generated was 3791 lines of code. 482 lines for Note and NoteType objects, the rest was other things.
  • The GenerateFiles function will generate files, but it doesn’t tell you where it put them.

Reference materials