Using NSwagStudio to Generate an SDK for an API

In a previous tutorial, I provided a high-level overview of five tools you can employ to generate SDKs for your API. Today, we'll delve deeper into how to utilize NSwagStudio, a GUI wrapper for NSwag, to craft your API SDK in .NET

Prerequisites

To get the most from this tutorial, you should have a foundational knowledge of C# and .NET, especially when it comes to working with ASP.NET APIs. If you're unfamiliar, I recommend browsing the Microsoft documentation here. Additionally, please ensure you have NSwagStudio installed—it's a user-friendly GUI for NSwag to help you generate API SDKs.

Choosing an API

For our purposes, we'll be generating an SDK for the JSON Placeholder API, a complimentary dummy API perfect for testing and prototyping. Remember, in real-world applications, you'd typically work with your production API.

To get started, click the Download button to retrieve the OpenAPI specification, which will be in a swagger.json format. We'll reference this file later.

SDK Generation

When generating the SDK, your options include NSwag CLI or NSwagStudio. While they essentially offer identical features, NSwag CLI shines in automation, perfect for deployment pipelines. However, for simplicity, this tutorial will focus on NSwagStudio due to its intuitive GUI.

Within NSwagStudio, the left section is dedicated to Inputs while the right caters to Output configurations.

Configuring Inputs

• Start by launching NSwagStudio.
• From the Runtime dropdown, select your .NET version— for this example, I've gone with .NET 7.0.
• Next, paste the content of the swagger.json you acquired earlier into the Specification JSON/YAML box. Alternatively, you can input the OpenAPI Specification file URL directly into the Specification URL.

Adjusting and Reviewing Outputs

• Move to the right section and select CSharpClient, indicating our aim to generate a C# SDK.
• Once chosen, the CSharp Client Settings will appear, though we'll only adjust a portion of these settings.

• In the Namespace field, designate the namespace for your SDK classes. I've selected JsonPlaceholderClient.
• Maintain the Generate exception classes option as it crafts classes to address API-specific errors. This can be useful, especially with an exception handling middleware.
• The Operation Generation Mode dictates the structure of the operations (API endpoints) in your final code. It's recommended to retain the MultipleClientsFromOperationId setting. To understand these strategies in depth, visit here.
• Ensure Use the base URL for the request remains active. This creates a BaseUrl property for your API, which is handy when your API exists across multiple environments, each with a unique base URL.
• Maintain the Inject HttpClient via constructor ... option. This allows consumers to inject their HTTP client, facilitating more streamlined lifecycle management. You can delve deeper into the HTTP client's usage here.
• While many settings like underlying .NET types, configuration of DTO classes, and JSON serialization settings can be adjusted, it's advisable to leave them in their default state unless a specific need arises.
• Deselect Generate DTO Types as DTOs are typically managed separately within projects.

Producing the Output

• Click Generate Outputs to view the resulting code.
• The produced code will appear on the left in the Output section. It showcases what NSwagStudio generates, highlighting features like the public Client(System.Net.Http.HttpClient httpClient) constructor and the PostsGETAsync method.

While you can now transfer this output code to your preferred IDE, remember it might require a bit of refactoring for enhanced readability. Tools like CodeRush can assist in this.

Note: Achieving similar results using the NSwag command line tool is entirely possible.

Releasing Your Code as an SDK

With your API client code ready, consider turning it into a NuGet package. Follow this guide to understand how others can utilize your creation.

Wrapping Up

In conclusion, NSwagStudio simplifies the process of generating a .NET SDK for your API based on a Swagger file. It's essential to remember that the quality of your Swagger file directly impacts your SDK, so invest time in refining it. If you're working within .NET, tools like Swashbuckle can assist. For more details, refer here.