Modo Spec-first (Beta)

O Modo Spec-first destina-se a equipas que pretendem que os ficheiros de especificação da API sejam a fonte de verdade. Neste modo, pode conceber e manter ficheiros OpenAPI ou Swagger diretamente no Apidog, pré-visualizar a documentação da API gerada à medida que edita e manter os ficheiros sincronizados com o Git.

Utilize o Modo Spec-first quando a sua equipa já trabalha com ficheiros de especificação YAML ou JSON, revê alterações da API através do Git ou pretende que a conceção da API se enquadre naturalmente num fluxo de trabalho de repositório de código.

Como funciona o Modo Spec-first

Num projeto Apidog normal, as APIs são geralmente criadas e editadas através de formulários visuais. Num projeto Spec-first, o espaço de trabalho principal é baseado em ficheiros.

Trabalha com ficheiros como:

openapi.yaml

openapi.json

Ficheiros Swagger 2.0

Ficheiros Markdown e outros ficheiros de apoio do projeto

O Apidog analisa os ficheiros de especificação e transforma-os numa estrutura de API navegável. Pode editar os ficheiros em bruto, utilizar formulários visuais suportados, validar a especificação, pré-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.

Ligue um fornecedor Git, como GitHub, GitLab, Azure DevOps ou Bitbucket.

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

Selecione o ramo principal com o qual o Apidog deve sincronizar.

Escolha se pretende instalar um webhook.

A instalação de um webhook permite que envios push no repositório Git acionem a sincronização automática. Normalmente, isto requer permissão de administrador no repositório. Se não tiver permissão de administrador, pode ignorar a instalação do webhook e sincronizar manualmente.

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

Após a criação, o Apidog executa a primeira sincronização. Se o ramo predefinido do repositório não for main, o Apidog utiliza o nome do ramo do repositório para o ramo principal do projeto.

Os projetos Spec-first não incluem dados de projeto de exemplo. O conteúdo da API provém dos seus ficheiros de especificação.

O espaço de trabalho Specs

Os projetos Spec-first incluem um espaço de trabalho Specs na barra lateral esquerda. Este é o local principal para gerir ficheiros de especificação e a sincronização com o Git.

O espaço de trabalho contém três áreas principais:

Explorador de ficheiros: navegue e gira ficheiros e pastas do repositório sincronizado.

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

Editor: edite ficheiros em vista de código ou, para nós OpenAPI suportados, em vista de formulário.

Quando seleciona um endpoint, esquema ou outro nó suportado na árvore de estrutura, o Apidog abre a parte relacionada do ficheiro de origem. Isto permite-lhe alternar entre a vista ao nível do ficheiro e a vista ao nível da API sem sair do espaço de trabalho Specs.

Editar ficheiros de especificação

O editor suporta diferentes tipos de ficheiro e modos de edição.

Vista de código

Utilize a vista Código para editar diretamente ficheiros YAML, JSON, Markdown e outros ficheiros de texto. Esta é a forma predefinida de trabalhar no Modo Spec-first.

Vista de formulário

Para nós OpenAPI suportados, o Apidog também disponibiliza uma vista Formulário. Isto permite-lhe editar campos comuns da API através de controlos estruturados, mantendo o ficheiro de especificação subjacente como a fonte de verdade.

A vista de formulário está disponível para nós suportados, tais como:

Visão geral da API

Endpoints

Esquemas

Definições

Se o ficheiro ou nó selecionado não puder ser editado na vista de formulário, o Apidog mantém-no na vista de código.

Validar e pré-visualizar durante a edição

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

Validação

O painel Validação mostra problemas detetados na especificação atual, incluindo avisos e erros. O distintivo de validação apresenta o número total de problemas detetados.

Utilize este painel para encontrar problemas de sintaxe, campos obrigatórios em falta 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 será apresentado na documentação da API gerada.

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

Visão geral da API

Endpoints

Esquemas

Definições

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

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

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

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

A Validação e a Pré-visualização utilizam o mesmo painel lateral. Abrir uma fecha a outra.

Sincronizar alterações do Git

Quando outros membros da equipa enviam alterações para o repositório ligado, pode obter os ficheiros mais recentes no Apidog.

Abra o espaço de trabalho Specs.

Clique no nome do ramo atual na barra lateral de Specs.

Clique em Git Pull.

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

Confirmar e enviar alterações para o Git

Depois de editar ficheiros no Apidog, envie as suas alterações de volta para o repositório ligado.

Edite um ou mais ficheiros no espaço de trabalho Specs.

Clique em Alterações para rever ficheiros modificados, adicionados, renomeados e eliminados.

Clique em Commit & Push.

No modal Push to Git repo, selecione os ficheiros que pretende incluir.

Introduza uma mensagem de commit.

Clique em Push.

Se não quiser manter as suas edições locais, utilize Descartar todas as alterações antes de enviar.

Gerir ramos

O Modo Spec-first suporta colaboração baseada em ramos. O Apidog associa ramos Git sincronizados a ramos do projeto, para que possa alternar entre versões da especificação.

Alternar entre ramos

Clique no nome do ramo na barra lateral de Specs e selecione outro ramo no menu pendente.

Monitorizar um ramo Git existente

Se existir um ramo no Git, mas ainda não tiver sido importado para o Apidog, clique em Importar novo ramo, selecione o ramo e importe-o. O Apidog começa então a monitorizar e sincronizar esse ramo.

Criar um ramo

Abra Definições do projeto > Git e ramos e clique em Novo ramo para criar um ramo a partir de um ramo de projeto existente.

Ressincronizar um ramo

Se a sincronização de um ramo falhar ou se os ficheiros parecerem desatualizados, utilize Ressincronizar em Definições do projeto > Git e ramos. Isto repõe o estado de sincronização desse ramo e importa novamente os ficheiros.

Ver registos de sincronização

Se uma sincronização falhar, abra as ações do ramo e escolha Ver registos para inspecionar os detalhes da sincronização.

Deixar de monitorizar ou eliminar um ramo

Eliminar um ramo monitorizado remove-o da configuração de sincronização do Apidog. Para ramos não principais, o registo do ramo do projeto também pode ser removido.

Sincronização por webhook e permissões

A sincronização por webhook é opcional, mas recomendada para equipas que pretendem que o Apidog se mantenha atualizado com envios push para o repositório.

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

O Apidog regista um webhook no fornecedor Git ligado.

Apenas eventos push suportados são processados.

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

Requisitos de permissão:

A instalação de um webhook normalmente requer permissão de administrador do repositório.

Enviar alterações requer permissão de escrita.

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

Se ignorou a instalação do webhook durante a criação do projeto, pode instalá-lo mais tarde a partir de Definições do projeto > Git e ramos.

Projetos Spec-first baseados em armazenamento

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

Estes projetos continuam a utilizar o espaço de trabalho Specs, a edição baseada em ficheiros, a validação, a pré-visualização e a gestão de ramos.

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

Git Pull aparece como Sync.

Commit & Push aparece como Save.

As informações do fornecedor Git e as definições de webhook externo ficam ocultas.

Notas e limitações

O Modo Spec-first está atualmente em beta.

O espaço de trabalho Specs aparece apenas em projetos Spec-first.

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

O ficheiro de especificação é a fonte de verdade. As alterações devem ser efetuadas através do espaço de trabalho Specs ou sincronizadas através do Git.

A instalação do webhook pode falhar se não tiver permissões suficientes no repositório. Pode continuar a utilizar a sincronização manual se tiver acesso de escrita.

Modo Spec-first (Beta)

Como funciona o Modo Spec-first#

Criar um projeto Spec-first#

O espaço de trabalho Specs#

Editar ficheiros de especificação#

Vista de código#

Vista de formulário#

Validar e pré-visualizar durante a edição#

Validação#

Pré-visualização#

Sincronizar alterações do Git#

Confirmar e enviar alterações para o Git#

Gerir ramos#

Alternar entre ramos#

Monitorizar um ramo Git existente#

Criar um ramo#

Ressincronizar um ramo#

Ver registos de sincronização#

Deixar de monitorizar ou eliminar um ramo#

Sincronização por webhook e permissões#

Projetos Spec-first baseados em armazenamento#

Notas e limitações#