Visual Studio Code Swagger

I like to add the code generation options directly to the Visual Studio project file. Right-click the project file of the.NET Core 5.0 Console Application and choose 'Edit Project File'. You will see a section that references the swagger. Json file we imported to generate the API client. SwaggerHub Extension for Visual Studio Code The SwaggerHub extension lets you view and edit your OpenAPI definitions stored in SwaggerHub directly from Visual Studio Code. You can access your organization's APIs and domains and sync the changes back to SwaggerHub. Both SwaggerHub SaaS and On-Premise are supported.

Visual Studio Code Swagger
Swagger Tutorial Visual Studio
Visual Studio Swagger Codegen
Visual Studio Swagger Code Gen
Visual Studio Code Swagger Viewer

A collection of Visual Studio C# custom tool code generators for Swagger / OpenAPI specification files

Features

Supports Visual Studio 2017 and 2019
Add New REST API Client to a project from an OpenAPI specification URL (e.g https://petstore.swagger.io/v2/swagger.json) using AutoRest, NSwag, Swagger Codegen, or OpenAPI Generator
Define custom namespace for the generated file
Auto-updating of generated code file when changes are made to the OpenAPI specification JSON or YAML file
Generate code using an NSwagStudio specification file by including it in the project and using the Generate with NSwag context menu

Custom Tools

AutoRestCodeGenerator - Generates a single file C# REST API Client using AutoRest.The resulting file is the equivalent of using the AutoRest CLI tool with:--csharp --input-file=[swaggerFile] --output-file=[outputFile] --namespace=[namespace] --add-credentials
NSwagCodeGenerator - Generates a single file C# REST API Client using the NSwag.CodeGeneration.CSharpnuget package v13.10.9
SwaggerCodeGenerator - Generates a single file C# REST API Client using Swagger Codegen CLI v3.0.14.The output file is the result of merging all the files generated using the Swagger Codegen CLI tool with:generate -l csharp --input-spec [swaggerFile] --output [output] -DapiTests=false -DmodelTests=false -DpackageName=[namespace] --skip-overwrite
OpenApiCodeGenerator - Generates a single file C# REST API Client using OpenAPI Generator v5.1.0.The output file is the result of merging all the files generated using the OpenAPI Generator tool with:generate -g csharp --input-spec [swaggerFile] --output [output] -DapiTests=false -DmodelTests=false -DpackageName=[namespace] --skip-overwrite

Dependencies

The custom tool code generators piggy back on top of well known Open API client code generators like AutoRest, NSwag, OpenAPI Generator, and Swagger Codegen CLI. These tools require NPM and the Java Runtime Environment to be installed on the developers machine. Alternative Java SDK implementations such as the OpenJDK works fine with this extension. By default, the path to java.exe is read from the JAVA_HOME environment variable, but is also configurable in the Settings screen

The Swagger Codegen CLI and OpenAPI Generator are distributed as JAR files and are downloaded on demand but requires the Java SDK to be installed on the machine. AutoRest is installed on-demand via NPM as a global tool and uses the latest available version. This means that using these custom tools have an initial delay upon first time use.

NSwagStudio is stand alone UI tool for editing a .nswag specification file for generating code. This tool is optional to install and official installation instructions are available on the NSwag Wiki on Github. If NSwagStudio is not installed on the machine then the Visual Studio Extension will install the NSwag CLI via NPM as a global tool using the latest available version.

The OpenAPI Generator and Swagger Codegen CLI code generators produces code that depends on the RestSharp and JsonSubTypes NuGet packages

The AutoRest code generator produces code that depends on the Microsoft.Rest.ClientRuntime and Newtonsoft.Json NuGet packages

The NSwag code generator produces code that depends on the Newtonsoft.Json NuGet package

This Visual Studio Extension will automatically add the required NuGet packages that the generated code depends on

Screenshots

Visual Studio Code Swagger

Settings

This extension will by default make some assumptions on the installation paths for Java, NSwag and NPM but also provides option pages for configuring this. The Swagger Codegen CLI and the OpenAPI Generator JAR files are by default downloaded to the user TEMP folder but it is also possible to specify to use existing JAR files

Supports customising how AutoRest generates code based on the C# generator settings that the AutoRest CLI tool provides

Supports customising how NSwag generates code using the properties exposed by the NSwag NuGet package

Supports customising how the .nswag file is generated using a subset of the options available in NSwag Studio

This extension collects errors and tracks feature usages to a service called Exceptionless. This is done anonymously using a support key and a generated anonymous identity based on a secure hash of username@host

For tips and tricks on software development, check out my blog

If you find this useful and feel a bit generous then feel free to buy me a coffee :)

Recently I talked about some of the new features in .NET 5.0 and preview versions of Visual Studio 16.8 and 16.9 with respect to ASP.NET Core Web API Projects. The first announcement I mentioned was the built-in support for OpenAPI and Swagger UI via Swashbuckle in the new ASP.NET Core 5 Web API Project Template, and the other announcement was a new feature introduced in Visual Studio 2019 that allows you to publish the web API to Azure API Management Services as part of the flow of publishing the ASP.NET Core Web API. Both of these tutorials mention Swashbuckle to generate the OpenAPI Specification Document. If you're generating an OpenAPI Specification Document for your ASP.NET Core Web API, you can use this same document to generate a client to consume your web API, which is what I will demonstrate in this ASP.NET Core Web API tutorial.

Sample Weather Forecast ASP.NET Core Web API

This tutorial assumes you have created a new ASP.NET Core 5 Web API project, which includes a sample weather forecast API that uses Swashbuckle to generate both an OpenAPI Specification Document and Swagger UI to explore and test the API.

I only want to make one change to this project, which I called WebApi. I want to modify the HTTPGet Attribute on the Get() method of the WeatherForecastController to include a route name of 'GetForecast' as shown below.

This route name gets added to the OpenAPI Specification Document as an operationId which will be used as a method name on the client generated in Visual Studio. If this isn't clear, it will be after we generate the client that will consume this web API.

Run the Web API Project to launch a browser that will display the Swagger UI. Click on the link to the swagger.json file in the Swagger UI to display the OpenAPI Specification Document. Save the file to disk. Remember where you save the swagger file, because we will be using the file to generate the client to consume the web API.

Create .NET Core 5.0 Console Application

Create a .NET Core 5.0 Console Application, ClientApi, in the same solution as the ASP.NET Core 5 Web API project. The console application will consume the sample weather service API. Right-click 'dependencies' and choose Add Connected Service. From here we want to add an OpenAPI Service Reference. Navigate to the Add new API service reference dialog and browse for the swagger file you saved earlier. Don't worry about adding a namespace and other additional settings as we will add these directly to the Visual Studio project file. Click 'Finish' to watch Visual Studio 2019 generate a client for the ASP.NET Core Web API using the swagger file (e.g. OpenAPI Specification Document).

Modify Code Generation Options in Visual Studio Project File

There are a number of options you can add for the code generator. At a minimum, I like to specify the namespace, class name, and output path for the OpenAPI client generated by Visual Studio using NSwag. We'll be importing this namespace and using the class name when we consume the API in our .NET Core 5.0 Console Application.

Save the project file when you're done editing it. I typically delete the 'bin' and 'obj' directories in my Visual Studio project and re-build the project. This causes the code generator to run again, using the code generation options we just added to the project file.

Swagger Tutorial Visual Studio

Using the NSwag Code Generated OpenAPI Client

We're now ready to consume the ASP.NET Core 5 Web API using the client generated by NSwag based on the OpenAPI Specification Document. Shown below is a simple .NET Core 5 Console Application that calls the ASP.NET Core Web API to get the weather forecast.

You can see how the code generation options we specified in our Visual Studio project impact the code we have written. First, the class name is WeatherServiceClient, which is the name we specified in the code generation options. We import the ClientApi.Services namespace, which is also the namespace we specified for the client in the code generation options.

In addition, notice the name of the method we are calling on the client to retrieve the weather forecast, GetForecastAsync. 'GetForecast' is the route name we added to the ASP.NET Core Web API. As mentioned above, this route name gets added to the OpenAPI Specification Document as an operationId, which is used to generate the name of the method on the client.

You can run the console application to consume the web API. Make sure you specify both projects as startup projects for your solution.

Visual Studio Swagger Codegen

Wrap Up

If this is your first time using code generation to create an OpenAPI client in Visual Studio, congratulations. You've accomplished a lot during the tutorial.

First, we created an ASP.NET Core 5 Web API using Visual Studio. The new Web API template now includes Swashbuckle.AspNetCore and is configured to create the OpenAPI Specification Document and Swagger UI. We added a custom route name to the Web API, which generated an operationId in the swagger file. This operationId was used as the name of the method on our code-generated API client. We then saved the swagger.json file from the link on the Swagger UI so we could later use it for code generation.

Visual Studio Swagger Code Gen

We then created a .NET Core 5 Console Application in the same solution and added an OpenAPI service reference using the OpenAPI Specification Document we saved earlier. We customized the code generation options and then generated the new API client.

Visual Studio Code Swagger Viewer

Finally, we used the code generated API client in the console application to consume the web API!