webapiclientgen

Los generadores de API web de cliente fuertemente tipados generan códigos API de cliente en C# y TypeScript desde la API web ASP.NET (Core) directamente sin involucrar a Swagger/OpenAPI o Swashbuckle, maximizando así el soporte para los tipos de datos de su enfoque Code First de ASP.NET Web API. .

Productos

Este proyecto ofrece estos productos:

1. Generador de código para API de cliente fuertemente tipado en C# compatible con .NET y Xamarin.Forms.
2. Generadores de código para API de cliente fuertemente tipado en TypeScript para jQuery, Angular 2+, Aurelia, Axios y Fetch API.
3. TypeScript CodeDOM, un componente .NET CodeDOM para TypeScript para desarrollar generadores de código TypeScript.
4. POCO2TS.exe, un programa de línea de comandos que genera interfaces TypeScript a partir de clases POCO.
5. Fonlow.Poco2Ts, un componente que genera interfaces TypeScript a partir de clases POCO.
6. Complementos para jQuery, AXIOS, Fetch API, Aurelia, Angular 2+ y Angular Typed Reactive Forms.
7. Fonlow.DataOnlyExtensions con convertidores JSON para manejar escenarios de solo fecha entre los clientes y el servidor que se encuentran en diferentes zonas horarias. También está disponible un paquete .NET Framework.

Casos de uso y descargas

Los productos se lanzan principalmente a través de NuGet.

1. Genere la API del cliente C# y luego use el paquete Fonlow.WebApiClientGenCore
2. Genere la API del cliente TypeScript, luego use uno de los complementos de Fonlow.WebApiClientGenCore:
   1. Biblioteca auxiliar jQuery y HttpClient
   2. angulares 6+
   3. Angular 6+, más creación de FormGroup para formularios reactivos con descripción
   4. AXIOS
   5. aurelia
   6. Obtener API
3. Desarrolle un generador de código TypeScript a través del enfoque CodeDOM, luego use el paquete Fonlow.TypeScriptCodeDOMCore.
4. Desarrolle un generador de código TypeScript a través del enfoque CodeDOM para POCO y más, luego use el paquete Fonlow.Poco2TSCore o use scripts de PowerShell 7.
5. Genere interfaces de tipo TypeScript y luego use Poco2TSCore.exe, una aplicación de consola.
6. Desarrolle una función que lea documentos XML de un ensamblado .NET y luego use el paquete Fonlow.DocCommentCore.

Consejos:

• OpenApiClientGen, basado en componentes clave de WebApiClientGen, es un derivado para generar códigos API de cliente en C# y TypeScript de acuerdo con un archivo de definición de Swagger/Open API Especificación.
• WebApiClientGen no utiliza definiciones Swagger/OpenAPI, pero genera códigos a partir de información de tipo de tiempo de ejecución de una API web en ejecución de la compilación de depuración, eliminando las limitaciones inherentes de OpenAPI frente a tipos .NET y API web para brindar una mejor experiencia de desarrollador en ASP. NET (Core) Desarrolladores de API web.

Observaciones:

• El desarrollo comenzó en el año 2015 y admitió .NET Framework, luego .NET Core 2. Y la etiqueta "LastCore31" marca la última instantánea que admite .NET Framework 4.6.2 y .NET Core 3.1.
• A partir del 10 de febrero de 2021, el desarrollo solo admitirá .NET 5 en adelante.
• Los contenidos wiki sobre .NET Framework se conservarán en un futuro previsible.

Características clave

1. Los códigos de API del cliente generados se asignan directamente desde los métodos del controlador de API web, los tipos primitivos de .NET y las clases POCO. Esto es similar a lo que ofrece svcutil.exe en WCF.
2. Se copian los comentarios de documentos de los métodos del controlador y las clases POCO.
3. Algunos atributos de validación se utilizan para generar comentarios de documentos para códigos TypeScript.

Beneficios clave para la experiencia del desarrollador

1. WebApiClientGen se integra perfectamente con ASP.NET Core Web API con muy pocos pasos/gastos generales para configurar, mantener y sincronizar entre la API web y las API del cliente, durante el desarrollo de software ágil o RAD.
2. Admite todos los tipos primitivos de .NET, incluido el decimal.
3. Admite DataTime, DataTimeOffset, DateOnly, Array, Tuple, Dynamic Object, Dictionary y KeyValuePair
4. Los códigos generados fuertemente tipados están sujetos a la verificación de tipos en tiempo de diseño y a la verificación de tipos en tiempo de compilación.
5. Proporcionar un alto nivel de abstracción, protegiendo a los desarrolladores de aplicaciones de detalles técnicos repetitivos de prácticas RESTful y códigos tradicionales de llamadas AJAX.
6. La rica metainformación, incluidos los comentarios de documentos, hace que IDE Intellisense sea más útil, por lo que los desarrolladores de aplicaciones tienen menos necesidad de leer documentos API separados.
7. Comentarios de documentos generados basados ​​en atributos de validación de .NET.
8. Comentarios de documentos generados basados ​​en tipos numéricos, DateOnly y GUID para códigos TypeScript.
9. Los códigos TypeScript generados se ajustan al modo estricto de TypeScript y los códigos Angular 2+ generados se ajustan al modo estricto de Angular.

Ejemplos

1. Clases POCO
2. API web
3. Códigos API C# de cliente generados
4. Códigos de cliente usando la biblioteca generada en C#
5. Modelos de datos de cliente generados y API en TypeScript para jQuery, Angular 2, Aurelia y Axios.
6. Códigos de cliente usando la biblioteca generada en TypeScript
7. Demostración en línea con Angular Heroes alojada en GitHub.IO hablando con un backend real

Observaciones:

1. Los códigos JavaScript compilados a partir de códigos TypeScript generados podrían usarse en aplicaciones JS; sin embargo, obviamente no habrá información de tipo disponible, mientras que los programadores de aplicaciones aún pueden disfrutar del sentido inteligente y la abstracción de los detalles de AJAX.
   1. Las aplicaciones React y Vue.js suelen utilizar Axios o Fetch API para solicitudes HTTP. Desde junio de 2019, babel admite espacios de nombres gracias a esta solicitud de extracción, por lo que debería poder programar React TSX con códigos TypeScript generados.

Conceptos

1. Los proveedores/desarrolladores de API web deben proporcionar bibliotecas de API de cliente a los desarrolladores de programas de cliente, como lo harían Google y Amazon, etc., para que la API web RESTful llegue a consumidores más amplios (internos y externos) de manera eficiente.
2. Para los desarrolladores de clientes, los prototipos de funciones clásicas como ReturnType DoSomething(Type1 t1, Type2 t2 ...) son la función API, y el resto son los detalles de implementación técnica del transporte: TCP/IP, HTTP, SOAP, orientado a recursos, CRUD- URI basados ​​en, RESTful, XML y JSON, etc. El prototipo de función y un documento API deberían ser lo suficientemente buenos para llamar a la función API.
3. Cuanto mejor se separen las preocupaciones en el diseño de su API web, más se beneficiará de los componentes de este proyecto para entregar valores comerciales antes, con menos códigos hechos a mano, menos tareas repetitivas y menos posibilidades de errores humanos.

Prácticas de programación esperadas

Prototipo de función fuertemente tipada

ReturnType DoSomething(Type1 t1, Type2 t2 ...)

		[ HttpGet ]
		[ Route ( "getPerson/{id}" ) ]
		public Person GetPerson ( long id )

Validación de Modelos a través de Middleware

En lugar de escribir códigos explícitos para validar la carga útil de la solicitud, se espera que utilice middleware para validar. Por ejemplo:

 public void ConfigureServices ( IServiceCollection services )
{
	services . AddControllers (
		options =>
		{
			options . Filters . Add ( new ValidateModelAttribute ( ) ) ; // wholesale style to check model binding for all API calls.

Referencias:

• Validación de modelos en ASP.NET Web API
• Validación de modelos en ASP.NET Core MVC y Razor Pages

Validación del modelo mediante ApiControllerAttribute

Por ejemplo:

	[ ApiController ]
	[ Route ( "api/[controller]" ) ]
	public class HeroesController : ControllerBase
	{

Códigos de estado HTTP distintos de 2xx manejados por middleware, opcional

Incluso si escribe códigos explícitamente en una función API para manejar excepciones y devolver códigos de estado HTTP que no sean 2xx, debe tener una red segura para detectar excepciones no detectadas y devolver códigos de estado HTTP.

Referencias:

• Middleware central ASP.NET

Requisitos previos

Lado del servidor:

1. NET 7/8
2. Agregue CodeGenController.
3. En los códigos de inicio del servicio, agregue lo siguiente:

 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

Observaciones:

• Microsoft ha estado lanzando actualizaciones importantes de .NET (Core) cada año desde 2016; las bibliotecas de este repositorio generalmente seguirán la última aproximadamente medio año después.
• Las bibliotecas públicas tienen .NET una versión posterior a la última versión, mientras que la aplicación de demostración ASP.NET y los conjuntos de pruebas de integración con la API de cliente .NET generada tienen la versión actual de .NET.

Lado del cliente .NET:

1. .NET Framework 4.5.2, o Universal Windows, o Mono.Android, o Xamarin.iOS, o .NET Core 2.0/2.1/3 y .NET 5
2. Bibliotecas cliente ASP.NET Web API 2.2
3. Json.NET de Newtonsoft para aplicación de tipo de contenido/json
4. Herramientas de compilación de Microsoft 2015

NewtonSoft.Json o System.Text.Json

A partir de .NET 7, para la serialización System.Text.Json vuelve a ensamblar más del 95% de NewtonSoft.Json. Sólo hay unos pocos casos extremos de estructuras POCO complejas que System.Text.Json no puede manejar.

WebApiClientGen es compatible tanto en el lado del servidor como en el lado del cliente C#. Para clientes C#, puede usar "UseSystemTextJson" en la configuración de Codegen.

Sin embargo, si su aplicación involucra estructuras POCO complejas, usar NewtonSoft.Json es una apuesta segura a partir de .NET 7.

Lado del cliente de TypeScript:

1. compilador de mecanografiado
2. jQuery
3. angulares 2-17
4. aurelia
5. axios
6. Obtener API

Para obtener más detalles, consulte:

1. wiki
2. Configuración explicada
3. Genere la API de cliente C# .NET para la API web ASP.NET
4. Generar API de cliente TypeScript para API web ASP.NET
5. API web ASP.NET, Angular2, TypeScript y WebApiClientGen
6. Genere la API de cliente C# para la API web ASP.NET Core
7. Soluciones previstas para las limitaciones intencionadas de los generadores de clientes OpenAPI fuertemente tipados. El artículo solo utiliza OpenApiClientGen como ejemplo, mientras que los principios y soluciones se pueden aplicar a los códigos generados por WebApiClientGen para sus aplicaciones cliente.
8. Sólo fecha en ASP.NET Core 6

Aplicaciones de demostración

Las aplicaciones de demostración en este repositorio son principalmente para probar WebApiClientGen durante el desarrollo. Y hay otras aplicaciones de demostración en los siguientes repositorios, que demuestran cómo las aplicaciones del mundo real podrían utilizar WebApiClientGen:

1. Ejemplos de WebApiClientGen para .NET Framework, .NET Standard, Xamarin y vue TS.
2. Demostración de .NET Core para ASP.NET Core MVC, Web API, ASP.NET Core + Angular, MAUI, fetchAPI, vue TS y React TS.
3. WebApiClientGen y Swagger

Estas aplicaciones de demostración se mantienen activamente y se mantienen actualizadas con los últimos marcos. Si todavía utiliza algunos marcos más antiguos como Angular 4 o 5 o .NET Core 2.0, puede navegar a las etiquetas respectivas de los repositorios y realizar el pago.

Gira de héroes

Tour of Heroes es la aplicación de demostración oficial del tutorial de Angular.

Para ilustrar la experiencia del programador al usar WebApiClientGen, las siguientes aplicaciones de demostración están diseñadas con un diseño arquitectónico similar para las mismas características funcionales en varios marcos de desarrollo o bibliotecas, sin embargo, hablando con un backend real.

1. Angular 2+ y formas reactivas escritas
2. Xamarin
3. MAUI. Migrado de Xamarin Heroes.
4. Aurelia. Suite de pruebas de integración incluida.
5. Reaccionar. Suite de pruebas de integración incluida.
6. Blazor independiente

NewtonSoft.Json o System.Text.Json

Si bien WebApiClientGen admite ambos, el soporte principal se ha trasladado a System.Text.Json desde 2024.

NewtonSoft.Json todavía tiene algunas ventajas en ciertos escenarios y contextos:

1. Si tiene muchas clases POCO decoradas por DataContractAttributes, debido a que admiten aplicaciones heredadas o admiten la serialización XML y JSON, NewtonSoft.Json le brinda soporte inherente, mientras que System.Text.Json proporciona soporte indirecto y problemático desde .NET 7.
2. Para algunos tipos de matrices y dinámicas, NewtonSoft.Json es aún mejor.