Nswag C# (How It Works For Developers)

APIs are essential in today's software development environment because they facilitate communication between various software systems and components. For developers to use APIs efficiently, there must be thorough and understandable documentation. Two effective tools that can help the C# API documentation workflow are NSwag C# and IronPDF. This post will discuss how to use NSwag to generate API specifications with .NET Core and produce high-quality PDF documents from these specifications using IronPDF.

How to Use NSwag in C#

1. Create a RESTful web API using Swagger UI.
2. Create a C# console application.
3. Install the NSwag library.
4. Import the namespace and create the object.
5. Process the Swagger JSON to C# code.
6. Execute the code and display the result.

Understanding NSwag

A .NET Swagger toolchain called NSwag was created to make it easier to create Swagger specifications, or OpenAPI documents, for APIs constructed using ASP.NET Web API, ASP.NET Core, or other .NET frameworks.

Features of NSwag

Production of Swagger Specs

Controllers, models, and .NET assemblies can all be used by NSwag to automatically produce Swagger specs. NSwag generates comprehensive documentation that covers API endpoints, request/response forms, authentication techniques, and more by examining the structure of the API code.

Connectivity to .NET Projects

Developers can easily include Swagger generation into their development processes by integrating NSwag with .NET projects. Developers can ensure that the documentation is updated with the codebase by adding NSwag to a .NET Core project, which will automatically produce Swagger specifications each time the project is built.

Personalization and Expansion

With the wide range of customization possibilities offered by NSwag, developers may easily adapt the generated Swagger specifications to meet their unique needs. Developers have control over many components of the generated documentation, including response codes, parameter explanations, and route naming conventions, through configuration settings and annotations.

Getting Started with NSwag

Setting Up NSwag in C# Console App

The NSwag Base Class Library includes the core, Annotation, and code generation namespace, which should be available by installing from NuGet. To integrate NSwag into a C# application to generate code and Swagger specifications, and how NSwag may improve the efficiency of the development process.

Implementing NSwag in Windows Console and Forms

Through automated client generation, developers can efficiently produce code for accessing APIs straight from within their desktop apps by integrating NSwag into a Windows desktop application. When developing desktop applications that communicate with online services or RESTful APIs, it can be quite helpful.

NSwag can be used in web applications to generate API documentation for internal APIs and client code for consuming external APIs. This aids developers in keeping their applications' frontend and backend components consistent.

NSwag C# Example

Here is an example of code that shows you how to use NSwag to produce C# client code:

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
using System.Net.Http;
using System.IO;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        using (var wclient = new System.Net.WebClient())
        {
            // Create JSON file data from the Swagger .NET Core web API
            var document = await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"));
            var settings = new CSharpClientGeneratorSettings
            {
                ClassName = "Weather",
                CSharpGeneratorSettings = { Namespace = "Demo" }
            };

            var generator = new CSharpClientGenerator(document, settings);
            var code = generator.GenerateFile();
            var assembly = CompileCode(code);
            var clientType = assembly.GetType("Demo.WeatherClient"); // Replace with your actual client class name
            using (var httpClient = new HttpClient())
            {
                var client = (IApiClient)Activator.CreateInstance(clientType, httpClient);
                var result = await client.GetWeatherForecastAsync();
                foreach (var item in result)
                {
                    Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}");
                }
            }
        }
    }

    static Assembly CompileCode(string code)
    {
        using (var memoryStream = new MemoryStream())
        {
            var assemblyPath = Path.GetDirectoryName(typeof(object).Assembly.Location);
            var references = new List<MetadataReference>
            {
                MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location),
                MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")),
                MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Private.CoreLib.dll"))
            };

            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .WithOptions(new Microsoft.CodeAnalysis.CSharp.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary))
                .AddReferences(references)
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code));

            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in emitResult.Diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }

    public interface IApiClient
    {
        // Replace with your actual method name and return type
        Task<List<WeatherForecast>> GetWeatherForecastAsync();
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public int TemperatureF { get; set; }
        public string Summary { get; set; }
    }
}

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
using System.Net.Http;
using System.IO;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        using (var wclient = new System.Net.WebClient())
        {
            // Create JSON file data from the Swagger .NET Core web API
            var document = await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"));
            var settings = new CSharpClientGeneratorSettings
            {
                ClassName = "Weather",
                CSharpGeneratorSettings = { Namespace = "Demo" }
            };

            var generator = new CSharpClientGenerator(document, settings);
            var code = generator.GenerateFile();
            var assembly = CompileCode(code);
            var clientType = assembly.GetType("Demo.WeatherClient"); // Replace with your actual client class name
            using (var httpClient = new HttpClient())
            {
                var client = (IApiClient)Activator.CreateInstance(clientType, httpClient);
                var result = await client.GetWeatherForecastAsync();
                foreach (var item in result)
                {
                    Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}");
                }
            }
        }
    }

    static Assembly CompileCode(string code)
    {
        using (var memoryStream = new MemoryStream())
        {
            var assemblyPath = Path.GetDirectoryName(typeof(object).Assembly.Location);
            var references = new List<MetadataReference>
            {
                MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location),
                MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")),
                MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Private.CoreLib.dll"))
            };

            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .WithOptions(new Microsoft.CodeAnalysis.CSharp.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary))
                .AddReferences(references)
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code));

            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in emitResult.Diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }

    public interface IApiClient
    {
        // Replace with your actual method name and return type
        Task<List<WeatherForecast>> GetWeatherForecastAsync();
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public int TemperatureF { get; set; }
        public string Summary { get; set; }
    }
}

Imports NSwag.CodeGeneration.CSharp
Imports NSwag
Imports System.Reflection
Imports System.CodeDom.Compiler
Imports Microsoft.CodeAnalysis
Imports System.Net.Http
Imports System.IO
Imports System.Collections.Generic
Imports System.Threading.Tasks

Friend Class Program
	Shared Async Function Main(ByVal args() As String) As Task
		Using wclient = New System.Net.WebClient()
			' Create JSON file data from the Swagger .NET Core web API
			Dim document = Await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"))
			Dim settings = New CSharpClientGeneratorSettings With {
				.ClassName = "Weather",
				.CSharpGeneratorSettings = { [Namespace] = "Demo" }
			}

			Dim generator = New CSharpClientGenerator(document, settings)
			Dim code = generator.GenerateFile()
			Dim assembly = CompileCode(code)
			Dim clientType = assembly.GetType("Demo.WeatherClient") ' Replace with your actual client class name
			Using httpClient As New HttpClient()
				Dim client = DirectCast(Activator.CreateInstance(clientType, httpClient), IApiClient)
				Dim result = Await client.GetWeatherForecastAsync()
				For Each item In result
					Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}")
				Next item
			End Using
		End Using
	End Function

	Private Shared Function CompileCode(ByVal code As String) As System.Reflection.Assembly
		Using memoryStream As New MemoryStream()
			Dim assemblyPath = Path.GetDirectoryName(GetType(Object).Assembly.Location)
			Dim references = New List(Of MetadataReference) From {MetadataReference.CreateFromFile(GetType(Object).GetTypeInfo().Assembly.Location), MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")), MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Private.CoreLib.dll"))}

			Dim compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient").WithOptions(New Microsoft.CodeAnalysis.CSharp.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)).AddReferences(references).AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code))

			Dim emitResult = compilation.Emit(memoryStream)
			If Not emitResult.Success Then
				Console.WriteLine("Compilation errors:")
				For Each diagnostic In emitResult.Diagnostics
					Console.WriteLine(diagnostic)
				Next diagnostic
				Return Nothing
			End If
			memoryStream.Seek(0, SeekOrigin.Begin)
			Return System.Reflection.Assembly.Load(memoryStream.ToArray())
		End Using
	End Function

	Public Interface IApiClient
		' Replace with your actual method name and return type
		Function GetWeatherForecastAsync() As Task(Of List(Of WeatherForecast))
	End Interface

	Public Class WeatherForecast
		Public Property [Date]() As DateTime
		Public Property TemperatureC() As Integer
		Public Property TemperatureF() As Integer
		Public Property Summary() As String
	End Class
End Class

For the API we wish to use, we specify the Swagger specification's URL (swaggerUrl). Then the client code generated and executed into a DLL assembly is defined. OpenApiDocument is employed to load the Swagger document asynchronously from the given URL, using FromJsonAsync. To alter the generated client code, we adjust the code generator's settings (CSharpClientGeneratorSettings). In this example, the produced client code's class name and namespace are specified.

From the loaded Swagger document, we construct an instance of CSharpClientGenerator and use it to produce the client code. The created client code is saved to the designated output path. We respond to any exceptions or errors that may arise during the procedure, displaying the relevant notifications on the console.

NSwag Operation

Generating Client Code

NSwag can use a Swagger specification to generate client code in many languages, including Java, TypeScript, and C#. This makes it simple for developers to use APIs in their applications.

Generating Server Code

Using a Swagger specification as a basis, NSwag may also produce server code, such as ASP.NET Core controllers. This helps to scaffold server-side code for API implementations quickly.

Producing Interactive API Documentation

Given a Swagger specification, NSwag may produce interactive API documentation, such as Swagger UI. An interface that is easy to use is provided by this documentation for exploring and testing API endpoints.

Producing Proxy Classes

To integrate with SOAP-based APIs, NSwag can produce proxy classes. This enables programmers to use produced client code to access SOAP services from within their applications.

Verifying Swagger Specifications

NSwag is capable of verifying Swagger specifications to make sure they follow the OpenAPI/Swagger standard. This makes it easier to see any errors or discrepancies in the API documentation.

Integrating NSwag with IronPDF

Developers can improve the workflow for API documentation by utilizing the advantages of both technologies by integrating NSwag with IronPDF. Developers can produce thorough, offline-ready .NET web API documentation that is readily available and shareable by using NSwag to generate Swagger specifications and IronPDF to transform them into PDFs. The following procedures are part of the integration process:

IronPDF excels in HTML to PDF conversion, ensuring precise preservation of original layouts and styles. It's perfect for creating PDFs from web-based content such as reports, invoices, and documentation. With support for HTML files, URLs, and raw HTML strings, IronPDF easily produces high-quality PDF documents.

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

Imports IronPdf

Friend Class Program
	Shared Sub Main(ByVal args() As String)
		Dim renderer = New ChromePdfRenderer()

		' 1. Convert HTML String to PDF
		Dim htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>"
		Dim pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent)
		pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf")

		' 2. Convert HTML File to PDF
		Dim htmlFilePath = "path_to_your_html_file.html" ' Specify the path to your HTML file
		Dim pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath)
		pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf")

		' 3. Convert URL to PDF
		Dim url = "http://ironpdf.com" ' Specify the URL
		Dim pdfFromUrl = renderer.RenderUrlAsPdf(url)
		pdfFromUrl.SaveAs("URLToPDF.pdf")
	End Sub
End Class

Install IronPDF

• Start the Visual Studio project.
• Choose "Tools" > "NuGet Package Manager" > "Package Manager Console".
• Open your command prompt and in the Package Manager Console, type the following command:

Install-Package IronPdf

• Alternatively, you can install IronPDF by using NuGet Package Manager for Solutions.
• Explore and select the IronPDF package from the search results, and then click the "Install" option. Visual Studio will handle the download and installation on your behalf.

• NuGet will install the IronPDF package and any dependencies required for your project.
• After installation, IronPDF can be utilized for your project.

Install Through the NuGet Website

For additional information regarding IronPDF's features, compatibility, and available downloads, visit the IronPDF page on NuGet.

Utilize DLL to Install

Alternatively, you can incorporate IronPDF directly into your project by using its DLL file. To download the ZIP file containing the DLL, click the IronPDF download link. Unzip the file and add the DLL to your project.

Implementing Logic

By utilizing NSwag, developers can create API documentation and client code for using APIs more quickly by using CodeGeneration.CSharp in conjunction with IronPDF. The following steps are part of the integration workflow:

1. Generate Client Code: To create C# client code from Swagger specs, use NSwag.CodeGeneration.CSharp. The creation of client classes and methods for communicating with the API endpoints is automated in this step.
2. Utilize NSwag to Get Data: To produce JSON documentation from Swagger specs, use CodeGeneration.CSharp. In this stage, the request/response formats, authentication techniques, and API client endpoints are created into human-readable documentation.
3. Convert JSON to PDF: To convert the generated code result to a PDF document, use IronPDF. In this stage, the HTML text is converted into a polished PDF document that is ready for sharing and distribution.
4. Improve PDF Documentation: Add more content to the PDF documentation using IronPDF, such as headers, footers, watermarks, or unique branding. This stage gives developers the ability to personalize the PDF documentation's look and branding to suit their tastes.

using IronPdf;
using System.Text;
using System.Collections.Generic;

StringBuilder sb = new StringBuilder();

foreach (var item in result)
{
    sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>");
}

var renderer = new HtmlToPdf();
var pdf = renderer.RenderHtmlAsPdf(sb.ToString());
pdf.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

using IronPdf;
using System.Text;
using System.Collections.Generic;

StringBuilder sb = new StringBuilder();

foreach (var item in result)
{
    sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>");
}

var renderer = new HtmlToPdf();
var pdf = renderer.RenderHtmlAsPdf(sb.ToString());
pdf.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

Imports IronPdf
Imports System.Text
Imports System.Collections.Generic

Private sb As New StringBuilder()

For Each item In result
	sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>")
Next item

Dim renderer = New HtmlToPdf()
Dim pdf = renderer.RenderHtmlAsPdf(sb.ToString())
pdf.SaveAs("output.pdf")
Console.WriteLine("PDF generated successfully!")
Console.ReadKey()

The code above accesses the retrieved data from the result object and appends the fields Date, TemperatureF, TemperatureC, and Summary to paragraphs in a loop. It then specifies the output file path for the PDF, then notifies the user that a PDF has been generated successfully.

Below is the result from the above code.

Conclusion

CodeGeneration NSwag technologies like CSharp and IronPDF work well together to streamline client code production and API documentation processes. Developers may speed up the creation of API-driven solutions, automate the creation of API documentation, and produce professional-looking PDF publications by integrating these tools into C# applications. NSwag.CodeGeneration.CSharp with IronPDF offers developers a complete solution for efficiently documenting APIs and producing client code in C#, whether they are developing desktop, web, or cloud-based apps.

The Lite bundle includes a perpetual license, one year of software maintenance, and an upgrade to the library. IronPDF offers free licensing with restrictions on redistribution and time. Users can assess the solution during the trial period without having to see a watermark. For additional information on the price and license, please see IronPDF's licensing information. Go to the Iron Software libraries page for additional information about Iron Software's product libraries.