Automatizacao De Clientes De Api Uma Abordagem Eficiente Com Github Actions E Openapi

Automatizando a Geração de Clientes de API: Melhore sua Produtividade com GitHub Actions

No desenvolvimento de software, a integração contínua e a entrega contínua (CI/CD) são fundamentais para aumentar a produtividade e minimizar erros. Um desafio comum é garantir que os clientes de API (componentes que consomem APIs) estejam sempre atualizados com as mudanças nas APIs. A falta de sincronia pode levar a falhas e inconsistências no sistema. Para resolver esse problema, uma estratégia eficaz é automatizar a geração de clientes de API sempre que uma nova versão da API é publicada. Este artigo discute como você pode usar o GitHub Actions para gerar e atualizar automaticamente clientes de API, focando em ferramentas como NSwag e Kiota, para garantir que os clientes de API estejam sempre em conformidade com a versão mais recente da API.

Objetivos

Promover maior produtividade: Automatizar a geração de clientes de API reduz o tempo gasto pelos desenvolvedores em tarefas repetitivas, permitindo que eles se concentrem em atividades mais complexas.
Diminuir o risco de erros na programação: A automação garante que os clientes de API sejam gerados de maneira consistente e conforme os contratos de API mais recentes, reduzindo erros de integração.
Atualização dos DTOs: Manter os Data Transfer Objects (DTOs) sempre atualizados conforme a evolução da API, garantindo que o cliente de API e a API estejam sempre em sincronia.

Pré-requisitos

Repositório de API hospedado no GitHub
Configuração de GitHub Actions
Ferramenta para geração de clientes de API (por exemplo, NSwag, Kiota, Swagger Codegen)

Conceitos Básicos

OpenAPI (Swagger)

OpenAPI, anteriormente conhecido como Swagger, é uma especificação para a criação de interfaces de API RESTful. Ele permite que desenvolvedores definam a estrutura de suas APIs de forma padronizada, facilitando a documentação, o desenvolvimento e a integração entre serviços.

Benefícios do uso de OpenAPI:

Documentação Automatizada: Geração automática de documentação detalhada da API.
Interoperabilidade: Facilita a integração com outras ferramentas e serviços.
Validação e Testes: Ferramentas para validação e testes automáticos da API.
Geração de Clientes: Possibilidade de gerar clientes de API em várias linguagens de programação.

NSwag

NSwag é uma ferramenta popular para a geração de clientes de API e documentação a partir de especificações OpenAPI. Ele suporta a geração de clientes em C#, TypeScript e outras linguagens, além de permitir a personalização dos clientes gerados.

Benefícios do NSwag:

Suporte a múltiplas linguagens: Gera clientes de API em várias linguagens de programação.
Personalização: Permite personalizar a geração de clientes conforme suas necessidades.
Integração com .NET: Fácil integração com projetos .NET.

Kiota

Kiota é uma ferramenta da Microsoft para a geração de clientes de API a partir de especificações OpenAPI. Ela é projetada para ser altamente configurável e extensível, facilitando a integração com o ecossistema Microsoft.

Benefícios do Kiota:

Integração com Azure: Ótima integração com serviços do Azure e outras ferramentas da Microsoft.
Alta configurabilidade: Permite ajustes finos na geração de clientes de API.
Suporte a .NET e TypeScript: Gera clientes de API para .NET e TypeScript, com suporte para outras linguagens no futuro.

Passo a Passo

1. Configuração do Swagger na API

Para gerar clientes de API automaticamente, sua API deve fornecer uma especificação OpenAPI (Swagger). Certifique-se de que sua API esteja configurada para gerar o arquivo swagger.json.

public void ConfigureServices(IServiceCollection services) { 
    services.AddSwaggerGen(c => { 
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); 
    }); 
}

2. Configuração do GitHub Actions

Crie um arquivo YAML no seu repositório GitHub para configurar o GitHub Actions. Este arquivo define o pipeline que será executado sempre que uma nova versão da API for publicada.

name: Generate API Client
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Set up .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '8.0.x'
    - name: Restore dependencies
      run: dotnet restore
    - name: Build API project
      run: dotnet build --configuration Release
    - name: Generate API client with NSwag
      run: |
        dotnet tool install --global NSwag.ConsoleCore
        export PATH="$PATH:/home/runner/.dotnet/tools"
        nswag openapi2csclient /input:swagger.json /output:Client.cs        
    - name: Generate API client with Kiota
      run: |
        dotnet tool install --global Microsoft.OpenApi.Kiota
        kiota --input swagger.json --language csharp --output ./GeneratedClient        
    - name: Commit and push generated client
      run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "github-actions[bot]@users.noreply.github.com"
        git add .
        git commit -m "Update API client"
        git push origin main

3. Detalhes do Projeto de Componente

Onde as Fontes Ficam

Os arquivos fonte do cliente de API gerado serão armazenados em um diretório específico dentro do repositório, como ./GeneratedClient para o Kiota ou na raiz do projeto para o NSwag.

Criação do Projeto de Componente

Para organizar o cliente de API como um projeto separado, você pode criar um projeto de biblioteca dentro da sua solução. Por exemplo, um projeto de biblioteca .NET pode ser criado da seguinte forma:

dotnet new classlib -o ApiClientLibrary

Após gerar o cliente de API, mova os arquivos gerados para o diretório ApiClientLibrary.

Atualização do Pacote

Sempre que houver uma nova publicação da API, o pipeline GitHub Actions atualizará os arquivos do cliente de API e fará commit dessas mudanças no repositório. Para facilitar a distribuição, você pode configurar a publicação do pacote para um registro de pacotes, como o NuGet.

Adicione um passo no pipeline para empacotar e publicar a biblioteca:

- name: Pack and push to NuGet
  run: |
    dotnet pack ApiClientLibrary/ApiClientLibrary.csproj -c Release -o ./nupkgs
    dotnet nuget push ./nupkgs/*.nupkg -k ${{ secrets.NUGET_API_KEY }} -s https://api.nuget.org/v3/index.json

Customizações

Tanto o NSwag quanto o Kiota permitem customizações avançadas. Você pode adicionar configurações personalizadas no arquivo de configuração do NSwag ou passar parâmetros adicionais para o Kiota.

Exemplo de configuração personalizada para NSwag:

- name: Generate API client with NSwag
  run: |
    dotnet tool install --global NSwag.ConsoleCore
    export PATH="$PATH:/home/runner/.dotnet/tools"
    nswag openapi2csclient /input:swagger.json /output:Client.cs /namespace:MyNamespace

Para o Kiota, você pode especificar configurações adicionais conforme necessário.

Conclusão

Automatizar a geração de clientes de API utilizando GitHub Actions, NSwag e Kiota é uma excelente forma de aumentar a produtividade da equipe e reduzir erros. Essa abordagem garante que os clientes de API estejam sempre atualizados conforme as últimas mudanças na API, proporcionando uma integração mais suave e eficiente.