webapiclientgen

Geradores de API Web de cliente fortemente tipados geram códigos de API de cliente em C# e TypeScript da API Web ASP.NET (Core) diretamente, sem envolver Swagger/OpenAPI ou Swashbuckle, maximizando assim o suporte para tipos de dados de sua abordagem Code First da API Web ASP.NET .

Produtos

Este projeto oferece estes produtos:

1. Gerador de código para API de cliente fortemente tipada em C# com suporte para .NET e Xamarin.Forms.
2. Geradores de código para API de cliente fortemente tipada em TypeScript para jQuery, Angular 2+, Aurelia, Axios e Fetch API.
3. TypeScript CodeDOM, um componente .NET CodeDOM para TypeScript para desenvolver geradores de código TypeScript.
4. POCO2TS.exe, um programa de linha de comando que gera interfaces TypeScript a partir de classes POCO.
5. Fonlow.Poco2Ts, um componente que gera interfaces TypeScript a partir de classes POCO.
6. Plugins para jQuery, AXIOS, Fetch API, Aurelia, Angular 2+, bem como Angular Typed Reactive Forms.
7. Fonlow.DataOnlyExtensions com conversores JSON para lidar com cenários apenas de data entre clientes e servidores que ficam em fusos horários diferentes. Um pacote .NET Framework também está disponível.

Casos de uso e downloads

Os produtos são lançados principalmente por meio do NuGet.

1. Gere a API do cliente C# e use o pacote Fonlow.WebApiClientGenCore
2. Gere a API do cliente TypeScript e use um dos plug-ins do Fonlow.WebApiClientGenCore:
   1. Biblioteca auxiliar jQuery e HttpClient
   2. Angular 6+
   3. Angular 6+, além de criação de FormGroup para formulários reativos com descrição
   4. AXIOS
   5. Aurélia
   6. Buscar API
3. Desenvolva o gerador de código TypeScript por meio da abordagem CodeDOM e, em seguida, use o pacote Fonlow.TypeScriptCodeDOMCore.
4. Desenvolva o gerador de código TypeScript por meio da abordagem CodeDOM para POCO e muito mais e, em seguida, use o pacote Fonlow.Poco2TSCore ou use scripts do PowerShell 7.
5. Gere interfaces do tipo TypeScript e use Poco2TSCore.exe, um aplicativo de console.
6. Desenvolva um recurso que leia o documento XML de um assembly .NET e, em seguida, use o pacote Fonlow.DocCommentCore.

Dicas:

• OpenApiClientGen baseado nos principais componentes do WebApiClientGen é um spin-off para gerar códigos de API de cliente em C# e TypeScript de acordo com um arquivo de definição de especificação Swagger/Open API.
• WebApiClientGen não utiliza definições Swagger/OpenAPI, mas gera códigos a partir de informações de tipo de tempo de execução de uma API Web em execução da compilação de depuração, livrando-se das limitações inerentes do OpenAPI em relação aos tipos .NET e API Web para fornecer melhor experiência de desenvolvedor ao ASP. NET (núcleo) desenvolvedores de API da Web.

Observações:

• O desenvolvimento começou no ano de 2015 com suporte para .NET Framework, depois .NET Core 2. E a tag "LastCore31" serve para marcar o último snapshot com suporte para .NET Framework 4.6.2 e .NET Core 3.1.
• A partir de 10/02/2021, o desenvolvimento oferecerá suporte apenas a .NET 5 e posteriores.
• O conteúdo do Wiki sobre o .NET Framework será mantido em um futuro próximo.

Principais recursos

1. Os códigos da API do cliente gerados são mapeados diretamente a partir dos métodos do controlador da API da Web, tipos primitivos .NET e classes POCO. Isso é semelhante ao que o svcutil.exe no WCF oferece.
2. Os comentários do documento dos métodos do controlador e das classes POCO são copiados.
3. Alguns atributos de validação são usados ​​para gerar comentários de documentos para códigos TypeScript.

Principais benefícios para a experiência do desenvolvedor

1. WebApiClientGen é perfeitamente integrado à API Web ASP.NET Core com muito poucas etapas/despesas gerais para configurar, manter e sincronizar entre API Web e APIs de cliente, durante RAD ou desenvolvimento ágil de software.
2. Suporta todos os tipos primitivos do .NET, incluindo decimal.
3. Suporte DataTime, DataTimeOffset, DateOnly, Array, Tuple, Objeto Dinâmico, Dicionário e KeyValuePair
4. Códigos gerados fortemente tipados estão sujeitos à verificação de tipo em tempo de design e verificação de tipo em tempo de compilação.
5. Fornece alto nível de abstração, protegendo os desenvolvedores de aplicações de detalhes técnicos repetitivos de práticas RESTful e códigos tradicionais de chamadas AJAX.
6. Metainformações ricas, incluindo comentários de documentos, tornam o intellisense do IDE mais útil, de modo que os desenvolvedores de aplicativos tenham menos necessidade de ler documentos de API separados.
7. Comentários de documentos gerados com base em atributos de validação do .NET.
8. Comentários de documentos gerados com base em tipos numéricos, DateOnly e GUID para códigos TypeScript.
9. Os códigos TypeScript gerados estão em conformidade com o modo estrito TypeScript e os códigos Angular 2+ gerados estão em conformidade com o modo estrito Angular.

Exemplos

1. Aulas POCO
2. API Web
3. Códigos C# da API do cliente gerados
4. Códigos de cliente usando a biblioteca gerada em C#
5. Modelos de dados de clientes gerados e API em TypeScript para jQuery, para Angular 2, para Aurelia e para Axios
6. Códigos de cliente usando a biblioteca gerada em TypeScript
7. Demonstração online com Angular Heroes hospedado no GitHub.IO conversando com um backend real

Observações:

1. Códigos JavaScript compilados a partir de códigos TypeScript gerados podem ser usados ​​em aplicativos JS, no entanto, obviamente nenhuma informação de tipo estará disponível, enquanto os programadores de aplicativos ainda podem aproveitar o intellisense e a abstração dos detalhes do AJAX.
   1. Os aplicativos React e Vue.js normalmente usam Axios ou Fetch API para solicitações HTTP. Desde junho de 2019, o babel oferece suporte a namespaces graças a esta solicitação pull, então você deve ser capaz de programar React TSX com códigos TypeScript gerados.

Conceitos

1. Os fornecedores/desenvolvedores de API da Web devem fornecer bibliotecas de API de cliente para desenvolvedores de programas de cliente, como Google e Amazon etc. fariam para fazer com que a API da Web RESTful alcance consumidores mais amplos (internos e externos) de forma eficiente.
2. Para desenvolvedores de clientes, protótipos de funções clássicas como ReturnType DoSomething(Type1 t1, Type2 t2 ...) são a função API, e o resto são os detalhes técnicos de implementação de transporte: TCP/IP, HTTP, SOAP, orientado a recursos, CRUD- URIs baseados, RESTful, XML e JSON, etc. O protótipo da função e um pedaço do documento da API devem ser bons o suficiente para chamar a função da API.
3. Quanto melhor você tiver a separação de interesses no design da sua API Web, mais você se beneficiará dos componentes deste projeto para entregar valores de negócio mais cedo, com menos códigos artesanais, menos tarefas repetitivas e menos chances de erros humanos.

Práticas de programação esperadas

Protótipo de função fortemente tipada

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

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

Validação de modelo por meio de middleware

Em vez de escrever códigos explícitos de validação da carga útil da solicitação, espera-se que você use middleware para validar. Por exemplo:

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

Referências:

• Validação de modelo na API Web ASP.NET
• Validação de modelo em páginas ASP.NET Core MVC e Razor

Validação de modelo através de ApiControllerAttribute

Por exemplo:

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

Códigos de status HTTP diferentes de 2xx manipulados por middleware, opcional

Mesmo se você escrever códigos explicitamente em uma função de API para lidar com exceções e retornar código de status HTTP diferente de 2xx, você deverá ter uma rede segura para capturar exceções não detectadas e retornar códigos de status HTTP.

Referências:

• Middleware principal do ASP.NET

Pré-requisitos

Lado do servidor:

1. .NET 7/8
2. Adicione CodeGenController.
3. Nos códigos de inicialização do serviço, adicione o seguinte:

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

Observações:

• A Microsoft tem lançado grandes atualizações do .NET (Core) todos os anos desde 2016. As bibliotecas neste repositório geralmente seguirão as últimas cerca de meio ano depois.
• As bibliotecas públicas estão com .NET uma versão atrás da versão mais recente, enquanto o aplicativo ASP.NET Demo e os conjuntos de testes de integração com API de cliente .NET gerada estão com a versão atual do .NET.

Lado do cliente .NET:

1. .NET Framework 4.5.2 ou Universal Windows ou Mono.Android ou Xamarin.iOS ou .NET Core 2.0/2.1/3 e .NET 5
2. Bibliotecas cliente ASP.NET Web API 2.2
3. Json.NET da Newtonsoft para aplicativo Content-Type/json
4. Ferramentas de compilação da Microsoft 2015

NewtonSoft.Json ou System.Text.Json

A partir do .NET 7, para serialização System.Text.Json remonta mais de 95% do NewtonSoft.Json. Existem apenas alguns casos extremos de estruturas POCO complexas que System.Text.Json não consegue manipular.

WebApiClientGen oferece suporte tanto no lado do servidor quanto no lado do cliente C#. Para clientes C#, você pode usar "UseSystemTextJson" nas configurações do codegen.

No entanto, se a sua aplicação envolve estruturas POCO complexas, usar NewtonSoft.Json é uma aposta segura a partir do .NET 7.

Lado do cliente TypeScript:

1. Compilador TypeScript
2. jQuery
3. Angular 2-17
4. Aurélia
5. Eixos
6. Buscar API

Para mais detalhes, verifique:

1. WIKI
2. Configurações explicadas
3. Gerar API de cliente C# .NET para API Web ASP.NET
4. Gerar API de cliente TypeScript para API Web ASP.NET
5. API Web ASP.NET, Angular2, TypeScript e WebApiClientGen
6. Gerar API cliente C# para API Web ASP.NET Core
7. Soluções pretendidas para limitações intencionais de geradores de clientes OpenAPI fortemente tipados. O artigo usa apenas OpenApiClientGen como exemplo, enquanto os princípios e soluções podem ser aplicados aos códigos gerados pelo WebApiClientGen para seus aplicativos clientes.
8. DataOnly no ASP.NET Core 6

Aplicativos de demonstração

Os aplicativos de demonstração neste repositório são principalmente para testar WebApiClientGen durante o desenvolvimento. E há outros aplicativos de demonstração nos repositórios a seguir, demonstrando como aplicativos do mundo real poderiam utilizar o WebApiClientGen:

1. Exemplos de WebApiClientGen para .NET Framework, .NET Standard, Xamarin e vue TS.
2. Demonstração do .NET Core para ASP.NET Core MVC, API Web, ASP.NET Core + Angular, MAUI, fetchAPI, vue TS e React TS.
3. WebApiClientGen vs Swagger

Esses aplicativos de demonstração são mantidos ativamente e atualizados com as estruturas mais recentes. Se você ainda usa alguns frameworks mais antigos, como Angular 4 ou 5 ou .NET Core 2.0, você pode navegar até as respectivas tags dos repositórios e finalizar a compra.

Tour dos Heróis

Tour of Heroes é o aplicativo oficial de demonstração do tutorial Angular.

Para ilustrar a experiência do programador ao usar WebApiClientGen, os aplicativos de demonstração a seguir são criados com design de arquitetura semelhante para os mesmos recursos funcionais em várias estruturas ou bibliotecas de desenvolvimento, no entanto, conversando com um back-end real.

1. Angular 2+ e formulários reativos digitados
2. Xamarin
3. MAUI. Migrado do Xamarin Heroes.
4. Aurélia. Conjunto de testes de integração incluído.
5. Reagir. Conjunto de testes de integração incluído.
6. Blazor autônomo

NewtonSoft.Json ou System.Text.Json

Embora WebApiClientGen ofereça suporte a ambos, o suporte principal mudou para System.Text.Json desde 2024.

NewtonSoft.Json ainda tem algumas vantagens em determinados cenários e contextos:

1. Se você tiver muitas classes POCO decoradas por DataContractAttributes, devido ao suporte a aplicativos legados ou à serialização XML e JSON, NewtonSoft.Json oferece suporte inerente, enquanto System.Text.Json fornece algum suporte indireto e problemático desde o .NET 7.
2. Para alguns tipos de array e dinâmicos, NewtonSoft.Json ainda é melhor.