Você tem um conjunto de endpoints de API existentes e precisa produzir uma especificação OpenAPI para eles. Escrever manualmente o arquivo YAML ou JSON para cada rota, parâmetro e resposta é demorado e propenso a erros. O GitHub Copilot pode analisar seu código de endpoint e gerar a especificação OpenAPI automaticamente. Este artigo explica como usar o Copilot para gerar uma especificação OpenAPI completa a partir do seu código de endpoint existente.
Principais Conclusões: Gerando Especificações OpenAPI com GitHub Copilot
- Chat inline do Copilot com código de endpoint: Use Ctrl+I para invocar o Copilot em um arquivo de controlador e pedir para gerar a especificação OpenAPI para todos os endpoints no arquivo.
- Copilot Chat com seleção de múltiplos arquivos: Use Ctrl+Shift+I para abrir o painel de Chat e referenciar vários arquivos contendo suas rotas de API para uma especificação completa.
- Validação manual da especificação gerada: Sempre teste a saída com um linter como Swagger Editor ou Spectral para detectar esquemas ausentes e definições de caminho incorretas.
Como o Copilot Gera Especificações OpenAPI a partir do Código
O GitHub Copilot usa o contexto do seu código-fonte para inferir a estrutura dos seus endpoints de API. Ele lê as anotações de método HTTP, modelos de rota, declarações de parâmetros e tipos de retorno dos seus arquivos de controlador ou manipulador. Com base nesse contexto, o Copilot produz uma especificação OpenAPI 3.0 ou 3.1 em formato YAML ou JSON.
A especificação gerada inclui caminhos, operações, parâmetros de solicitação, corpos de solicitação e esquemas de resposta. O Copilot também pode gerar componentes reutilizáveis para modelos e respostas de erro se você fornecer contexto suficiente no seu código.
Pré-requisitos para Usar o Copilot para Geração de OpenAPI
Antes de começar, verifique se você tem o seguinte:
- GitHub Copilot ativado no seu IDE. Os IDEs suportados incluem Visual Studio Code, Visual Studio, IDEs JetBrains e Neovim.
- Seu código de endpoint de API escrito em uma linguagem que o Copilot suporta. Linguagens comuns incluem Python, JavaScript, TypeScript, C#, Java, Go, Ruby e PHP.
- Seus arquivos de controlador ou manipulador de rotas abertos no editor. O Copilot funciona melhor quando pode ver o contexto completo do arquivo.
Passos para Gerar Especificação OpenAPI a partir do Código de Endpoint
Siga estes passos para gerar uma especificação OpenAPI completa a partir do seu código de endpoint existente. Os passos assumem que você está usando o Visual Studio Code, mas o processo é semelhante em outros IDEs.
- Abra seu arquivo de controlador ou manipulador de rotas
Abra o arquivo que contém suas definições de endpoint de API. Por exemplo, um controlador Python Flask, um controlador C# ASP.NET Core ou um arquivo de rotas JavaScript Express. Certifique-se de que o arquivo seja a aba ativa no seu editor. - Invoque o chat inline do Copilot
Pressione Ctrl+I para abrir o chat inline do Copilot. Este chat está anexado ao seu arquivo atual. Digite um prompt que descreva o que você deseja. Por exemplo: “Gere uma especificação OpenAPI 3.0 para todos os endpoints neste arquivo”. Pressione Enter para enviar o prompt. - Revise a especificação gerada
O Copilot inserirá o YAML ou JSON OpenAPI gerado diretamente em uma nova área de resposta do chat. Revise os caminhos, parâmetros e esquemas. Verifique se os caminhos correspondem aos seus endpoints reais e se os métodos estão corretos. Se a saída estiver incompleta, refine seu prompt. Por exemplo, adicione “Inclua esquemas de corpo de solicitação para endpoints POST e PUT”. - Salve a especificação gerada em um novo arquivo
Copie a especificação gerada da resposta do chat. Crie um novo arquivo chamado openapi.yaml ou openapi.json no seu projeto. Cole a especificação neste arquivo. Salve o arquivo. - Gere especificação para vários arquivos usando o Copilot Chat
Se seus endpoints abrangem vários arquivos, abra o painel do Copilot Chat pressionando Ctrl+Shift+I. No chat, referencie os arquivos que deseja incluir. Por exemplo, digite: “@workspace gere uma especificação OpenAPI 3.0 para todos os endpoints nos arquivos routes/users.js e routes/products.js”. O Copilot analisará ambos os arquivos e produzirá uma especificação combinada.
Problemas Comuns e Como Lidar com Eles
A especificação gerada pode ter lacunas ou erros. Aqui estão os problemas mais comuns e como corrigi-los.
O Copilot omite alguns endpoints ou parâmetros
O Copilot pode pular endpoints que usam roteamento dinâmico ou vinculação complexa de parâmetros. Para corrigir isso, adicione um comentário no seu código que descreva o endpoint ausente. Por exemplo, acima de um manipulador de rota, adicione um comentário como: “GET /api/users/{id} retorna um objeto de usuário”. Em seguida, execute novamente o prompt de geração. O Copilot usará o comentário como contexto adicional.
Esquemas gerados são muito genéricos
Se seus modelos de resposta estão definidos em arquivos separados, o Copilot pode não incluir suas propriedades na especificação. Para resolver isso, abra os arquivos de modelo no seu editor antes de executar a geração. O Copilot verá as definições de modelo e incluirá seus campos no esquema. Alternativamente, no prompt do Copilot Chat, liste explicitamente os arquivos de modelo: “Use as definições de modelo de models/user.py para os esquemas de resposta”.
Especificação não valida contra os padrões OpenAPI
Após gerar a especificação, valide-a usando um linter OpenAPI. Instale o linter Spectral ou use o Swagger Editor online. Erros de validação comuns incluem campos operationId ausentes, parâmetros de caminho duplicados e códigos de resposta incorretos. Corrija-os manualmente na especificação gerada. Por exemplo, adicione um operationId único a cada operação de caminho, como getUserById.
Geração Inline do Copilot vs Copilot Chat para Geração de Especificação: Principais Diferenças
| Item | Geração Inline do Copilot (Ctrl+I) | Copilot Chat (Ctrl+Shift+I) |
|---|---|---|
| Escopo do contexto | Apenas o arquivo ativo | Vários arquivos via @workspace ou referências de arquivo |
| Melhor caso de uso | Especificação rápida para um arquivo de controlador | Especificação completa para projetos com vários arquivos |
| Local de saída | Área de resposta do chat inline | Área de resposta do painel de chat |
| Capacidade de refinar | Sim, com prompts de acompanhamento | Sim, com prompts de acompanhamento e referências de arquivo |
| Inclusão de arquivos de modelo | Apenas se os arquivos de modelo estiverem abertos no editor | Sim, referenciando explicitamente os arquivos de modelo |
Use a geração inline para um único arquivo de controlador quando precisar de um rascunho rápido. Use o Copilot Chat para projetos maiores com vários arquivos de rota e definições de modelo separadas.
Após gerar a especificação, sempre execute uma ferramenta de validação. O comando CLI do Spectral spectral lint openapi.yaml captura erros comuns. Corrija quaisquer problemas antes de usar a especificação para documentação ou geração de clientes. O Copilot também pode ajudar a corrigir erros de validação: cole a mensagem de erro no Copilot Chat e peça para corrigir a especificação.