In this post, we'll dive into the role of OpenAPI specifications and discuss two crucial tools that can simplify your interaction with them: NSwag and AutoRest. OpenAPI, a widely adopted standard for designing APIs, enables different software systems to communicate effectively. It's particularly valuable when integrating third-party services via API. But, generating the corresponding client code can be a tedious task. Let's consider an example:
You're developing a large-scale e-commerce platform, and a component of your system requires integrating a third-party shipping service API. The shipping service provides an extensive OpenAPI specification, but no pre-built .NET client library, leaving you the task of writing the client code manually. This is where code generation tools, such as NSwag and AutoRest, come in handy by automating this process.
NSwag
NSwag, an open-source toolchain for .NET and TypeScript, is a robust tool for generating client code and API documentation from OpenAPI specifications.
Installing NSwag
Getting started with NSwag is as straightforward as it gets. Installation is done as a .NET global tool with a simple command:
dotnet tool install --global NSwag.ConsoleCore
Generating API Clients with NSwag
Once NSwag is installed on your system, generating an API client boils down to running a command. This command can point to either a URL or a local file path leading to the OpenAPI specification document (typically swagger.json). For instance, if you are looking to generate a C# API client, you would use the following command:
nswag run /runtime:Net70 /p:Namespace="YourNamespace" /input:swagger.json /output:Client.cs
In this command, /runtime:Net70 specifies the runtime, /p:Namespace="YourNamespace" sets the namespace for the generated code, /input:swagger.json indicates the input OpenAPI specification file, and /output:Client.cs is the output file for the generated client.
Generating TypeScript Clients with NSwag
NSwag's versatility extends to TypeScript as well, allowing developers to generate TypeScript client code. The command needs a slight modification:
nswag run /runtime:Net70 /p:TypeScriptVersion=ES6 /input:swagger.json /output:Client.ts
Repeatable Generation
NSwag supports creating a configuration file (nswag.json), which encapsulates all the commands and options for code generation. This feature adds repeatability and consistency to the code generation process. You should use the nswag.json approach if you find yourself often re-generating your client and correlated models.
A GUI for NSwag
For those who are more visually inclined, NSwag offers NSwagStudio, a Windows desktop app that lets you configure the generation process visually, making it an attractive alternative. However, I found it useful only if you're doing a one-time setup and taking over the updates manually from there.
AutoRest
AutoRest, an open-source tool developed by Microsoft, is another great alternative for generating client libraries from OpenAPI specifications.
GitHub repository for AutoRest
Installing AutoRest
AutoRest is a Node.js tool and can be installed using npm (Node Package Manager) as follows:
npm install -g autorest
Generating API Clients with AutoRest
After AutoRest is installed, generating API clients can be done with a simple command. For instance, to generate a C# client, you would use:
autorest --input-file=https://my-api.com/swagger.json --csharp --output-folder=GeneratedClient --namespace=YourNamespace
In this command, --input-file=https://my-api.com/swagger.json specifies the input OpenAPI specification file, --csharp indicates the language of the client, --output-folder=GeneratedClient specifies the output directory, and --namespace=YourNamespace sets the namespace for the generated code.
Comparing NSwag and AutoRest
While NSwag and AutoRest bring similar functionalities to the table, they do have marked differences that could influence your choice.
- Platform and Language Support
Both tools support multiple languages. NSwag supports just C# and TypeScript, while AutoRest, being designed with a language-agnostic approach, supports a larger set of languages such as C#, TypeScript, Java, Python, and more. - Customizability
AutoRest shines with a remarkable level of control over the generated code. You can introduce settings in a configuration file to fine-tune the output to your liking. If you need to go a step further, you can even design new templates or create a new generator for your project's unique needs. - Ease of Use
NSwag wins the ease of use race, offering a simpler installation and usage process, particularly within a .NET environment. AutoRest can be more complex to set up and use, especially for developers unfamiliar with Node.js and npm. Plus, NSwag offers a GUI tool, NSwagStudio, for a more intuitive setup. - Repeatable Generation
While NSwag provides the nswag.json for easy repeatability, AutoRest lacks a similar feature out of the box.
In Conclusion
Generating code from OpenAPI specifications is something that both NSwag and AutoRest provide. The choice of tool will hinge on your specific project requirements, the programming language you're comfortable with, and personal preferences. Both tools are actively maintained and frequently updated, ensuring that no matter your choice, you're investing in a tool that will streamline your API development process and push your efficiency.
My recommendation is to stick to NSwag if you need to get started quickly to make things work, but if you want to come up with clean templates that could help you stay up-to-date with the latest features when integrating with third-party service, or if you want to offer a client library of your own in multiple different programming languages for one of the services you're maintaining, AutoRest might be a better choice.
Thank you for sticking to the end. If you have any questions, comments, or topics you'd like covered in future posts, please leave them in the comments below.
