Saltar al pie de página
  1. IronPDF
  2. Blog de IronPDF
  3. .NET Ayuda
  4. Nswag C#
.NET AYUDA

Nswag C# (Cómo Funciona para Desarrolladores)

Jacob Mellor, Director de Tecnología @ Team Iron
Jacob Mellor
Actualizado:

Las API son esenciales en el entorno de desarrollo de software actual porque facilitan la comunicación entre diversos sistemas y componentes de software. Para que los desarrolladores usen las API de manera eficiente, debe haber una documentación completa y comprensible. Dos herramientas efectivas que pueden ayudar en el flujo de trabajo de la documentación de API de C# son NSwag C# e IronPDF. Esta publicación discutirá cómo usar NSwag para generar especificaciones API con .NET Core y producir documentos PDF de alta calidad a partir de estas especificaciones usando IronPDF.

Cómo utilizar NSwag en C#

  1. Crea una API web RESTful usando Swagger UI.
  2. Crea una aplicación de consola en C#.
  3. Instala la biblioteca NSwag.
  4. Importa el espacio de nombres y crea el objeto.
  5. Procesa el JSON de Swagger a código C#.
  6. Ejecuta el código y muestra el resultado.

Entendiendo NSwag

Se creó una cadena de herramientas Swagger de .NET llamada NSwag para facilitar la creación de especificaciones Swagger, o documentos OpenAPI, para API construidas usando 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 ensamblajes .NET para producir automáticamente especificaciones Swagger. NSwag genera documentación completa que cubre puntos finales de API, formularios de solicitud/respuesta, técnicas de autenticación, y más al examinar 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 asegurar que la documentación esté actualizada con la base de código al agregar NSwag a un proyecto .NET Core, que automáticamente producirá especificaciones Swagger cada vez que se construya el proyecto.

Personalización y ampliació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. A través de configuraciones de configuración y anotaciones, los desarrolladores tienen control sobre muchos componentes de la documentación generada, incluidos los códigos de respuesta, las explicaciones de parámetros y las convenciones de nombres de rutas.

Cómo empezar con NSwag

Cómo configurar NSwag en la aplicación de consola de C

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 deberían estar disponibles instalando desde NuGet. Para integrar NSwag en una aplicación de 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 Administrador de Paquetes de Visual Studio e instalarlo

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

A través de la generación automática de clientes, los desarrolladores pueden producir eficazmente código para acceder a las API directamente desde dentro de 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 APIs RESTful, puede ser muy útil.

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

NSwag C# Ejemplo

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

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; }
    }
}
$vbLabelText   $csharpLabel

Para la API que deseamos usar, especificamos la URL de la especificación Swagger (swaggerUrl). Luego se define el código de cliente generado y ejecutado en un ensamblaje DLL. OpenApiDocument se emplea para cargar el documento Swagger de manera asíncrona desde la URL dada, usando FromJsonAsync. Para alterar el código de cliente generado, ajustamos la configuración del generador de código (CSharpClientGeneratorSettings). En este ejemplo, se especifica el nombre de la clase y el espacio de nombres del código de cliente generado.

A partir del documento Swagger cargado, construimos una instancia de CSharpClientGenerator y lo usamos para producir el código de cliente. El código de cliente creado se guarda en la ruta de salida designada. Respondemos a cualquier excepción o error que pueda surgir durante el procedimiento, mostrando las notificaciones relevantes en la consola.

NSwag C# (Cómo Funciona para Desarrolladores): Figura 2 - Salida de consola del código anterior

Funcionamiento deNSwag

Generación de código cliente

NSwag puede usar una especificación Swagger para generar código de cliente en muchos lenguajes, incluidos Java, TypeScript y C#. Esto hace que sea simple para los desarrolladores usar APIs en sus aplicaciones.

Generación de código de servidor

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

Producción de documentación interactiva de API

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

Producir clases proxy

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

Verificación de especificaciones Swagger

NSwag es capaz de verificar especificaciones Swagger para asegurarse de que sigan el estándar OpenAPI/Swagger. Esto facilita la detección de cualquier error o discrepancia en la documentación de la API.

Integración de NSwag con IronPDF

Los desarrolladores pueden mejorar el flujo de trabajo de la documentación de API utilizando las ventajas de ambas tecnologías al integrar NSwag con IronPDF. Los desarrolladores pueden producir documentación completa de API web .NET lista para usar sin conexión, que está fácilmente disponible y puede compartirse usando NSwag para generar especificaciones Swagger y IronPDF para transformarlas en PDFs. El siguiente procedimiento forma parte del proceso de integración:

IronPDF se destaca en la conversión de HTML a PDF, asegurando la preservación precisa de los diseños y estilos originales. Es perfecto para crear PDFs a partir de contenido basado en la web como informes, facturas y documentación. Con soporte para archivos HTML, URLs y cadenas HTML en bruto, IronPDF produce fácilmente documentos PDF de alta calidad.

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");
    }
}
$vbLabelText   $csharpLabel

Instalar IronPDF

  • Inicie el proyecto en Visual Studio.
  • Elija "Herramientas" > "Administrador de Paquetes NuGet" > "Consola del Administrador de Paquetes".
  • Abra su línea de comandos y en la Consola del Gestor de Paquetes, escriba el siguiente comando:
Install-Package IronPdf
  • Alternativamente, puede instalar IronPDF usando el Administrador de Paquetes NuGet para Soluciones.
  • Explore y seleccione el paquete IronPDF de los resultados de búsqueda y luego haga clic en la opción "Instalar". Visual Studio gestionará la descarga e instalación en su nombre.

NSwag C# (Cómo Funciona para Desarrolladores): Figura 3 - Instalar IronPDF desde el Administrador de Paquetes NuGet buscando IronPDF en la barra de búsqueda del Administrador de Paquetes NuGet, luego selecciona el proyecto y haz clic en el botón de instalación.

  • NuGet instalará el paquete IronPDF y cualquier dependencia requerida para su proyecto.
  • Después de la instalación, IronPDF se puede utilizar para su proyecto.

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

Para obtener información adicional sobre las características, la compatibilidad y las descargas disponibles de IronPDF, visite la página de IronPDF en NuGet.

Utilizar DLL para instalar

Alternativamente, puede incorporar IronPDF directamente en su proyecto usando su archivo DLL. Para descargar el archivo ZIP que contiene el DLL, haga clic en el enlace de descarga de IronPDF. Descomprima el archivo y agregue el DLL a su proyecto.

Implementación de la lógica

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

  1. Generar Código de Cliente: Para crear código de cliente en C# a partir de especificaciones Swagger, use NSwag.CodeGeneration.CSharp. La creación de clases y métodos de cliente para comunicarse con los puntos finales de la API se automatiza en este paso.
  2. Usar NSwag para obtener datos: Para producir documentación en JSON a partir de especificaciones Swagger, use CodeGeneration.CSharp. En esta etapa, los formatos de solicitud/respuesta, las técnicas de autenticación y los puntos finales de clientes API se crean en documentación legible por humanos.
  3. Convertir JSON a PDF: Para convertir el resultado de código generado en un documento PDF, use IronPDF. En esta etapa, el texto HTML se convierte en un documento PDF pulido listo para compartir y distribuir.
  4. Mejorar la Documentación en PDF: Agregue más contenido a la documentación en PDF usando IronPDF, como encabezados, pies de página, marcas de agua o marca única. Esta etapa brinda a los desarrolladores la capacidad de personalizar la apariencia y la marca de la documentación en PDF según sus gustos.
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();
$vbLabelText   $csharpLabel

El código anterior accede a los datos recuperados del objeto resultado y agrega los campos Date, TemperatureF, TemperatureC, y Summary a los párrafos en un bucle. Luego, especifica la ruta del archivo de salida para el PDF, luego notifica al usuario que se ha generado un PDF con éxito.

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

Las tecnologías CodeGeneration como CSharp e IronPDF trabajan bien juntas para optimizar los procesos de producción de código de cliente y documentación de APIs. Los desarrolladores pueden acelerar la creación de soluciones impulsadas por APIs, automatizar la creación de documentación de APIs, y producir publicaciones en PDF de aspecto profesional al integrar estas herramientas en aplicaciones de C#. NSwag.CodeGeneration.CSharp con IronPDF ofrece a los desarrolladores una solución completa para documentar APIs de manera eficiente y producir código de cliente en C#, ya sea que estén desarrollando aplicaciones de escritorio, web, o basadas en la nube.

El paquete Lite incluye una licencia perpetua, un año de mantenimiento de software, y una actualización a la biblioteca. IronPDF ofrece licencias gratuitas con restricciones en la redistribución y tiempo. Los usuarios pueden evaluar la solución durante el período de prueba sin tener que ver una marca de agua. Para obtener información adicional sobre el precio y la licencia, consulte la información de licencias de IronPDF. Vaya a la página de librerías de Iron Software para obtener información adicional sobre las librerías de productos de Iron Software.

Preguntas Frecuentes

¿Cómo puede NSwag ayudar con la generación de especificaciones de API en C#?

NSwag puede generar automáticamente especificaciones de API, conocidas como documentos Swagger o OpenAPI, a partir de proyectos .NET Core. Esto asegura que la documentación de la API siempre esté sincronizada con la base de código.

¿Cuál es el proceso para convertir especificaciones Swagger en documentos PDF?

Para convertir especificaciones Swagger en documentos PDF, puede usar IronPDF. Primero, genere la especificación Swagger usando NSwag, luego utilice IronPDF para convertir el contenido HTML de estas especificaciones en PDFs de alta calidad.

¿Cómo puedo integrar NSwag en un proyecto .NET?

Integrar NSwag en un proyecto .NET implica instalar la biblioteca NSwag a través de NuGet, configurarla para generar especificaciones Swagger durante el proceso de compilación y usar las especificaciones generadas para documentación y generación de código.

¿Puede NSwag generar tanto código de cliente como de servidor a partir de una especificación Swagger?

Sí, NSwag puede generar código de cliente en lenguajes como C#, Java y TypeScript, así como código del lado del servidor, como controladores ASP.NET Core, todo a partir de una sola especificación Swagger.

¿Cómo mejora IronPDF el flujo de trabajo de documentación de la API?

IronPDF mejora el flujo de trabajo de documentación de la API al permitir a los desarrolladores convertir documentación de API basada en HTML en documentos PDF profesionales y compartibles, haciendo que la información sea accesible sin conexión.

¿Qué pasos son necesarios para usar IronPDF en un proyecto de Visual Studio?

Para usar IronPDF en un proyecto de Visual Studio, instálelo a través del Administrador de Paquetes NuGet buscando IronPDF y haciendo clic en 'Instalar', o use la Consola del Administrador de Paquetes con el comando Install-Package IronPdf.

¿Cómo se puede generar documentación interactiva de la API usando NSwag?

NSwag puede generar documentación interactiva de la API produciendo una interfaz Swagger UI, que proporciona una interfaz amigable para explorar y probar los puntos finales de la API directamente en el navegador.

¿Cuáles son los beneficios de usar NSwag para la documentación de API?

NSwag automatiza la generación de documentación de API, asegurando que siempre esté actualizada con la base de código. También admite la creación de documentación interactiva y código del lado del cliente, agilizando el proceso de desarrollo.

¿Cómo trabaja IronPDF con contenido HTML para crear PDFs?

IronPDF convierte contenido HTML, incluyendo CSS y JavaScript, en formato PDF utilizando su motor de renderizado, lo que lo hace ideal para crear documentos precisos y listos para uso sin conexión a partir de contenido web.

Jacob Mellor, Director de Tecnología @ Team Iron
Jacob Mellor
  Chatea con el equipo de ingeniería ahora
Director de Tecnología

Jacob Mellor es Director de Tecnología en Iron Software y un ingeniero visionario que lidera la tecnología PDF en C#. Como el desarrollador original detrás de la base de código central de Iron Software, ha moldeado la arquitectura de productos de la compañía desde ...

Leer más

Artículos Relacionados

Prueba de 30 días → Producto completo. Sin límites. Sin tarjeta. Prueba gratis