Pruebas en un entorno real
Pruebe en producción sin marcas de agua.
Funciona donde lo necesites.
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.
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.
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.
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.
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.
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.
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.
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
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 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.
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.
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.
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.
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.
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:
Install-Package IronPdf
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.
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.
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.
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:
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.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.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
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.
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.
9 productos API .NET para sus documentos de oficina