AYUDA .NET

Nswag C# (Cómo funciona para desarrolladores)

Actualizado junio 6, a. m.

Introducción

Las API son esenciales en el entorno actual de desarrollo de software porque facilitan la comunicación entre diversos sistemas y componentes de software. Para que los desarrolladores utilicen las API con eficacia, debe haber documentos completos y comprensibles. Dos herramientas eficaces que pueden ayudar al flujo de trabajo de documentación de la API de C# son NSwag c# e IronPDF. En este artículo se explica cómo utilizar NSwag para generar API con .NET Core y producir documentos PDF de alta calidad a partir de estas especificaciones utilizando IronPDF.

Cómo utilizar NSwag en C#

Crear una API web restful utilizando Swagger UI.
Crear una aplicación de consola en c#.
Instale la biblioteca NSwag.
Importa el espacio de nombres y crea el objeto.
Procesar el código swagger JSON a c#.
Ejecuta el código y muestra el resultado.

Comprender el NSwag

Se creó una cadena de herramientas Swagger .NET llamada NSwag para facilitar la creación de especificaciones Swagger, o documentos OpenAPI, para API construidas con ASP.NET Web API, ASP.NET Core u otros marcos .NET.

Características de NSwag

Producción de especificaciones Swagger

NSwag puede utilizar controladores, modelos y ensamblados .NET para producir automáticamente especificaciones Swagger. NSwag genera documentación exhaustiva que cubre los puntos finales de la API, los formularios de solicitud/respuesta, las técnicas de autenticación, etc. mediante el examen de la estructura del código de la API.

Conectividad con proyectos .NET

Los desarrolladores pueden incluir fácilmente la generación de Swagger en sus procesos de desarrollo integrando NSwag con proyectos .NET. Los desarrolladores pueden asegurarse de que la documentación se actualiza con el código base añadiendo NSwag a un proyecto .NET core, que producirá automáticamente especificaciones Swagger cada vez que se construya el proyecto.

Personalización y expansión

Con la amplia gama de posibilidades de personalización que ofrece NSwag, los desarrolladores pueden adaptar fácilmente las especificaciones Swagger generadas para satisfacer sus necesidades únicas. Los desarrolladores tienen control sobre muchos componentes de la documentación generada, incluidos los códigos de respuesta, las explicaciones de los parámetros y las convenciones de nomenclatura de las rutas, a través de los ajustes de configuración y las anotaciones.

Primeros pasos con Nswag

Configuración de Nswag en C# aplicación de consola

La biblioteca de clases base Nswag incluye el núcleo, la anotación, y el espacio de nombres de generación de código, que debe estar disponible mediante la instalación de Nuget. Integrar NSwag en una aplicación C# para generar código y especificaciones Swagger, y cómo NSwag puede mejorar la eficiencia del proceso de desarrollo.

Nswag C# (Cómo funciona para desarrolladores): Figura 1 - Buscar Nswag en el Gestor de Paquetes de Visual Studio e instalarlo

Implementación de Nswag en la consola y formularios de Windows

Gracias a la generación automática de clientes, los desarrolladores pueden generar código de forma eficaz para acceder a las API directamente desde sus aplicaciones de escritorio integrando NSwag en una aplicación de escritorio de Windows. Cuando se desarrollan aplicaciones de escritorio que se comunican con servicios en línea o API RESTful, puede ser bastante útil.

NSwag puede utilizarse en aplicaciones web para generar documentación de API para API internas y código cliente para consumir API externas. Esto ayuda a los desarrolladores a mantener la coherencia entre los componentes frontend y backend de sus aplicaciones.

Nswag C# Ejemplo

Aquí hay un ejemplo de código que muestra cómo usar NSwag para producir código cliente C#:

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
class Program
{
    static async Task Main(string[] args)
    {
        System.Net.WebClient 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"));
        wclient.Dispose();
        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
        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);
            List<MetadataReference> references = new List<MetadataReference>();
            references.Add(MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")));
            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references);
            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                var diagnostics = emitResult.Diagnostics;
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }
    public interface IApiClient
    {
        Task<List<WeatherForecast>> GetWeatherForecastAsync(); // Replace with your actual method name and return type
    }
    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;
class Program
{
    static async Task Main(string[] args)
    {
        System.Net.WebClient 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"));
        wclient.Dispose();
        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
        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);
            List<MetadataReference> references = new List<MetadataReference>();
            references.Add(MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")));
            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references);
            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                var diagnostics = emitResult.Diagnostics;
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }
    public interface IApiClient
    {
        Task<List<WeatherForecast>> GetWeatherForecastAsync(); // Replace with your actual method name and return type
    }
    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
Friend Class Program
	Shared Async Function Main(ByVal args() As String) As Task
		Dim wclient As 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"))
		wclient.Dispose()
		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
		Dim 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 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 As New List(Of MetadataReference)()
			references.Add(MetadataReference.CreateFromFile(GetType(Object).GetTypeInfo().Assembly.Location))
			references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")))
			references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")))
			Dim compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient").AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(GetType(Object).Assembly.Location)).AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references)
			Dim emitResult = compilation.Emit(memoryStream)
			If Not emitResult.Success Then
				Dim diagnostics = emitResult.Diagnostics
				Console.WriteLine("Compilation errors:")
				For Each diagnostic In 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
		Function GetWeatherForecastAsync() As Task(Of List(Of WeatherForecast)) ' Replace with your actual method name and return type
	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

VB C#

Para la API que deseamos utilizar, especificamos la URL de la especificación Swagger (swaggerUrl). A continuación, se define el código cliente generado y ejecutado en un ensamblaje DLL. Se emplea OpenApiDocument. Para cargar el documento Swagger de forma asíncrona desde la URL dada, utiliza FromJsonAsync. Para modificar el código cliente generado, ajustamos la configuración del generador de código (CSharpClientGeneratorSettings). En este ejemplo, se especifican el nombre de clase y el espacio de nombres del código cliente producido.

A partir del documento Swagger cargado, construimos una instancia de CSharpClientGenerator y la utilizamos para producir el código cliente (código de cliente). El código cliente creado se guarda en la ruta de salida designada. Respondemos a las excepciones o errores que puedan surgir durante el procedimiento, mostrando las notificaciones pertinentes en la consola.

Nswag C# (Cómo funciona para desarrolladores): Figura 2 - Salida de la consola del código anterior

Operación NSwag

Generación de código cliente

NSwag puede utilizar una especificación Swagger para generar código cliente en muchos lenguajes, incluidos Java, TypeScript y C#. Esto facilita a los desarrolladores el uso de las API en sus aplicaciones.

Generación de código de servidor

Utilizando una especificación Swagger como base, NSwag también puede producir código de servidor, como controladores ASP.NET Core. Esto ayuda a armar rápidamente el código del lado del servidor para las implementaciones de API.

Producción de documentación interactiva de la API

Dada una especificación Swagger, NSwag puede producir documentación interactiva de la API, como Swagger UI. Esta documentación proporciona una interfaz fácil de usar para investigar y probar los puntos finales de la API.

Producción de clases proxy

Para integrarse con APIs basadas en SOAP, NSwag puede producir clases proxy. Esto permite a los programadores utilizar código cliente producido para acceder a los servicios SOAP desde sus aplicaciones.

Verificación de las especificaciones Swagger

NSwag es capaz de verificar las especificaciones Swagger para asegurarse de que siguen el estándar OpenAPI/Swagger. Esto facilita la detección de errores o discrepancias en la documentación de la API.

Integración de NSwag con IronPDF

Los desarrolladores pueden mejorar el flujo de trabajo para la documentación de API utilizando las ventajas de ambas tecnologías mediante la integración de NSwag con IronPDF. Los desarrolladores pueden producir una documentación de API web completa, lista para su uso fuera de línea, que esté disponible y se pueda compartir fácilmente utilizando NSwag para generar especificaciones Swagger e IronPDF para transformarlas en PDF documentación. Los siguientes procedimientos forman parte del proceso de integración:

Instalar IronPDF

Inicie el proyecto de Visual Studio.
Seleccione "Herramientas" > "Gestor de paquetes NuGet" > "Consola del gestor de paquetes".
Abra el símbolo del sistema y, en la consola del gestor de paquetes, escriba el siguiente comando:

Install-Package IronPdf

También puede instalar IronPDF utilizando NuGet Package Manager for Solutions.
Puede explorar y seleccionar el paquete IronPDF en los resultados de la búsqueda y, a continuación, hacer clic en la opción "Instalar". Visual Studio se encargará de la descarga y la instalación en su nombre.
NuGet instalará el paquete IronPDF y cualquier dependencia necesaria para su proyecto.
Tras la instalación, IronPDF puede utilizarse para su proyecto.

Instalación a través del sitio web de NuGet

Para obtener más información sobre las características de IronPDF, su compatibilidad y las descargas disponibles, visite su página en https://www.nuget.org/packages/IronPdf en el sitio web de NuGet.

Utilizar DLL para instalar

Como alternativa, puede incorporar IronPDF directamente a su proyecto utilizando su archivo DLL. Para descargar el archivo ZIP que contiene la DLL, haga clic aquí enlace. Descomprima el archivo y añada la DLL a su proyecto.

Para obtener el archivo ZIP que contiene la DLL. Una vez descomprimida, incorpora la DLL a tu proyecto.

Aplicación de la lógica

Utilizando NSwag, los desarrolladores pueden crear documentación API y código cliente para utilizar APIs más rápidamente utilizando CodeGeneration.CSharp junto con IronPDF. Los siguientes pasos forman parte del flujo de trabajo de integración:

Generar código cliente: Para crear código cliente C# a partir de especificaciones Swagger, utilice NSwag.CodeGeneration.CSharp. En este paso se automatiza la creación de clases y métodos cliente para comunicarse con los puntos finales de la API.
Utilizar NSwag para GetData: Para producir documentación JSON a partir de especificaciones Swagger, utilice CodeGeneration.CSharp. En esta fase, los formatos de solicitud/respuesta, las técnicas de autenticación y los puntos finales del cliente API se convierten en documentación legible por humanos.
Convertir JSON a PDF: Para convertir el resultado del código generado a un documento PDF, utilice IronPDF. En esta fase, el texto HTML se convierte en un documento PDF pulido y listo para compartir y distribuir.
Mejore la documentación PDF: Añada más contenido a la documentación PDF mediante IronPDF, como encabezados, pies de página, marcas de agua o marcas exclusivas. Esta etapa ofrece a los desarrolladores la posibilidad de personalizar el aspecto y la marca de la documentación PDF para adaptarla a sus gustos.

using IronPdf;        
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 IronPdf.HtmlToPdf();
var PDF = Renderer.RenderHtmlAsPdf(sb.ToString());
// Save PDF to file
PDF.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

using IronPdf;        
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 IronPdf.HtmlToPdf();
var PDF = Renderer.RenderHtmlAsPdf(sb.ToString());
// Save PDF to file
PDF.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

IRON VB CONVERTER ERROR developers@ironsoftware.com

VB C#

El código anterior accede a los datos recuperados del objeto resultante y añade los campos Date, TemperatureF, TemperatureC, y Summary a los párrafos en un bucle. A continuación, especifica la ruta del archivo de salida para el PDF y notifica al usuario que el PDF se ha generado correctamente.

A continuación se muestra el resultado del código anterior.

Nswag C# (Cómo funciona para desarrolladores): Figura 4 - Ejemplo de salida del código anterior

Conclusión

CodeGeneration Las tecnologías NSwag como CSharp e IronPDF funcionan bien juntas para agilizar los procesos de producción de código cliente y documentación de API. Los desarrolladores pueden acelerar la creación de soluciones basadas en API, automatizar la creación de documentación de API y producir publicaciones PDF de aspecto profesional integrando estas herramientas en aplicaciones C#. NSwag.CodeGeneration.CSharp` con IronPDF ofrece a los desarrolladores una solución completa para documentar eficientemente APIs y producir código cliente en C#, tanto si están desarrollando aplicaciones de escritorio, web o basadas en la nube.

El paquete $749 Lite incluye una licencia perpetua, un año de mantenimiento del software y una actualización de la biblioteca. IronPDF ofrece licencias gratuitas con restricciones de redistribución y temporales. Los usuarios pueden evaluar la solución durante el periodo de prueba sin tener que ver una marca de agua. Para obtener información adicional sobre el precio y la licencia, consulte la licencia de IronPDF página. Vaya a esta página para obtener más información sobre Iron Software bibliotecas.

< ANTERIOR
Dapper C# (Cómo funciona para desarrolladores)

SIGUIENTE >
Flunt C# (Cómo funciona para desarrolladores)