Modo Spec-first (Beta)

Modo Spec-first é destinado a equipes que desejam que os arquivos de especificação da API sejam a fonte da verdade. Nesse modo, você projeta e mantém arquivos OpenAPI ou Swagger diretamente no Apidog, visualiza a documentação de API gerada enquanto edita e mantém os arquivos sincronizados com o Git.

Use o Modo Spec-first quando sua equipe já trabalha com arquivos de especificação YAML ou JSON, revisa alterações de API por meio do Git ou deseja que o design de API se encaixe naturalmente em um fluxo de trabalho de repositório de código.

Como o Modo Spec-first funciona

Em um projeto regular do Apidog, as APIs geralmente são criadas e editadas por meio de formulários visuais. Em um projeto Spec-first, o workspace principal é baseado em arquivos.

Você trabalha com arquivos como:

openapi.yaml

openapi.json

Arquivos Swagger 2.0

Arquivos Markdown e outros arquivos de suporte do projeto

O Apidog analisa os arquivos de especificação e os transforma em uma estrutura de API navegável. Você pode editar os arquivos brutos, usar formulários visuais compatíveis, validar a especificação, visualizar a documentação gerada e enviar alterações de volta para o Git.

Criar um projeto Spec-first

Clique em + Novo Projeto.

No seletor de tipo de projeto, escolha Modo Spec-first.

Conecte um provedor Git, como GitHub, GitLab, Azure DevOps ou Bitbucket.

Selecione uma organização ou workspace e, em seguida, escolha um repositório existente ou crie um novo repositório se a opção estiver disponível.

Selecione a branch principal com a qual o Apidog deve sincronizar.

Escolha se deseja instalar um webhook.

Instalar um webhook permite que pushes no repositório Git acionem a sincronização automática. Isso geralmente requer permissão de administrador no repositório. Se você não tiver permissão de administrador, poderá ignorar a instalação do webhook e sincronizar manualmente.

Insira o nome do projeto, configure as permissões dos membros e clique em Criar.

Após a criação, o Apidog realiza a primeira sincronização. Se a branch padrão do repositório não for main, o Apidog usará o nome da branch do repositório para a branch principal do projeto.

Projetos Spec-first não incluem dados de projeto de exemplo. O conteúdo da API vem dos seus arquivos de especificação.

O workspace Specs

Projetos Spec-first incluem um workspace Specs na barra lateral esquerda. Esse é o principal local para gerenciar arquivos de especificação e sincronização com o Git.

O workspace contém três áreas principais:

Explorador de arquivos: navegue e gerencie arquivos e pastas do repositório sincronizado.

Árvore de estrutura da API: navegue pelo conteúdo OpenAPI analisado, como visão geral, endpoints, schemas e definições.

Editor: edite arquivos na visualização de código ou, para nós OpenAPI compatíveis, na visualização de formulário.

Quando você seleciona um endpoint, schema ou outro nó compatível na árvore de estrutura, o Apidog abre a parte relacionada do arquivo de origem. Isso permite que você alterne entre a visualização em nível de arquivo e a visualização em nível de API sem sair do workspace Specs.

Editar arquivos de especificação

O editor oferece suporte a diferentes tipos de arquivo e modos de edição.

Visualização de código

Use a visualização Código para editar YAML, JSON, Markdown e outros arquivos de texto diretamente. Essa é a forma padrão de trabalhar no Modo Spec-first.

Visualização de formulário

Para nós OpenAPI compatíveis, o Apidog também fornece uma visualização Formulário. Isso permite que você edite campos comuns de API por meio de controles estruturados, mantendo o arquivo de especificação subjacente como a fonte da verdade.

A visualização de formulário está disponível para nós compatíveis, como:

Visão geral da API

Endpoints

Schemas

Definições

Se o arquivo ou nó selecionado não puder ser editado na visualização de formulário, o Apidog manterá você na visualização de código.

Validar e visualizar durante a edição

O Modo Spec-first inclui ferramentas de validação e visualização no cabeçalho do editor.

Validação

O painel Validação mostra problemas detectados na especificação atual, incluindo avisos e erros. O indicador de validação exibe o número total de problemas detectados.

Use esse painel para encontrar problemas de sintaxe, campos obrigatórios ausentes e violações de regras antes de confirmar alterações.

Pré-visualização

O painel Pré-visualização mostra como o nó de especificação selecionado aparecerá na documentação de API gerada.

A pré-visualização está disponível para:

Visão geral da API

Endpoints

Schemas

Definições

Para endpoints, a Pré-visualização inclui:

Documentação: a documentação de endpoint gerada.

Experimentar: um painel de requisição para enviar uma requisição com base na definição do endpoint selecionado.

Para schemas, definições e nós de visão geral, a Pré-visualização mostra a visualização da documentação gerada.

Validação e Pré-visualização usam o mesmo painel lateral. Abrir um fecha o outro.

Sincronizar alterações do Git

Quando outros membros da equipe enviam alterações para o repositório conectado, você pode puxar os arquivos mais recentes para o Apidog.

Abra o workspace Specs.

Clique no nome da branch atual na barra lateral Specs.

Clique em Git Pull.

Se a sincronização por webhook estiver instalada, o Apidog também poderá receber eventos de push do provedor Git e acionar a sincronização automaticamente.

Fazer commit e push das alterações para o Git

Depois de editar arquivos no Apidog, envie suas alterações de volta para o repositório conectado.

Edite um ou mais arquivos no workspace Specs.

Clique em Alterações para revisar arquivos modificados, adicionados, renomeados e excluídos.

Clique em Commit & Push.

No modal Enviar para o repositório Git, selecione os arquivos que você deseja incluir.

Insira uma mensagem de commit.

Clique em Push.

Se você não quiser manter suas edições locais, use Descartar todas as alterações antes de fazer push.

Gerenciar branches

O Modo Spec-first oferece suporte à colaboração baseada em branches. O Apidog mapeia branches Git sincronizadas para branches de projeto para que você possa alternar entre versões da especificação.

Alternar branches

Clique no nome da branch na barra lateral Specs e selecione outra branch no menu suspenso.

Rastrear uma branch Git existente

Se uma branch existir no Git, mas ainda não tiver sido importada para o Apidog, clique em Importar nova branch, selecione a branch e importe-a. O Apidog então começa a rastrear e sincronizar essa branch.

Criar uma branch

Abra Configurações do projeto > Git e branches e clique em Nova branch para criar uma branch a partir de uma branch de projeto existente.

Ressincronizar uma branch

Se a sincronização de uma branch falhar ou os arquivos parecerem desatualizados, use Ressincronizar em Configurações do projeto > Git e branches. Isso redefine o estado de sincronização dessa branch e importa os arquivos novamente.

Visualizar logs de sincronização

Se uma sincronização falhar, abra as ações da branch e escolha Visualizar logs para inspecionar os detalhes da sincronização.

Parar de rastrear ou excluir uma branch

Excluir uma branch rastreada a remove da configuração de sincronização do Apidog. Para branches que não sejam a principal, o registro da branch do projeto também pode ser removido.

Sincronização por webhook e permissões

A sincronização por webhook é opcional, mas recomendada para equipes que desejam que o Apidog permaneça atualizado com os pushes do repositório.

Quando a sincronização por webhook está habilitada:

O Apidog registra um webhook no provedor Git conectado.

Somente eventos de push compatíveis são processados.

O Apidog verifica a assinatura ou o token do webhook antes de sincronizar.

Requisitos de permissão:

Instalar um webhook geralmente requer permissão de administrador do repositório.

Fazer push de alterações requer permissão de escrita.

Se a instalação do webhook for ignorada, a sincronização manual ainda estará disponível.

Se você ignorou a instalação do webhook durante a criação do projeto, poderá instalá-lo posteriormente em Configurações do projeto > Git e branches.

Projetos Spec-first baseados em armazenamento

Alguns projetos Spec-first podem usar o armazenamento interno do Apidog em vez de um repositório Git externo.

Esses projetos ainda usam o workspace Specs, edição baseada em arquivos, validação, pré-visualização e gerenciamento de branches.

Os rótulos da interface são ligeiramente diferentes:

Git Pull aparece como Sync.

Commit & Push aparece como Save.

As informações do provedor Git e as configurações de webhook externo ficam ocultas.

Observações e limitações

O Modo Spec-first está atualmente em beta.

O workspace Specs aparece apenas em projetos Spec-first.

Projetos Spec-first não criam dados de API de exemplo.

O arquivo de especificação é a fonte da verdade. As alterações devem ser feitas por meio do workspace Specs ou sincronizadas pelo Git.

A instalação do webhook poderá falhar se você não tiver permissão suficiente no repositório. Você ainda poderá usar a sincronização manual se tiver acesso de escrita.

Modo Spec-first (Beta)

Como o Modo Spec-first funciona#

Criar um projeto Spec-first#

O workspace Specs#

Editar arquivos de especificação#

Visualização de código#

Visualização de formulário#

Validar e visualizar durante a edição#

Validação#

Pré-visualização#

Sincronizar alterações do Git#

Fazer commit e push das alterações para o Git#

Gerenciar branches#

Alternar branches#

Rastrear uma branch Git existente#

Criar uma branch#

Ressincronizar uma branch#

Visualizar logs de sincronização#

Parar de rastrear ou excluir uma branch#

Sincronização por webhook e permissões#

Projetos Spec-first baseados em armazenamento#

Observações e limitações#