Extensões da especificação OpenAPI do Apidog

O Apidog oferece suporte a extensões personalizadas da especificação OpenAPI/Swagger que aprimoram os recursos de design e gerenciamento de APIs. Essas extensões permitem que você especifique metadados adicionais para os endpoints da sua API, como organização em pastas, status do endpoint e informações do mantenedor.

Este guia de referência documenta as extensões personalizadas x-apidog-* que podem ser usadas em suas especificações OpenAPI/Swagger para integração perfeita com os recursos do Apidog.

Especificar a pasta à qual um endpoint pertence

O Apidog priorizará o uso do campo x-apidog-folder para organizar endpoints. Se esse campo não existir, ele usará o primeiro valor no campo tags.

Use barras / para separar pastas de vários níveis. Observe que tanto a barra invertida \ quanto a barra / são caracteres especiais que exigem escape. Para representar o caractere barra /, use \/; e, para representar o caractere \, use \\.

Exemplo:

"paths": {
  "/pets": {
     "post": {
         ...
         "operationId": "addPet",     
         "x-apidog-folder": "Pet Store/Pet Information"
     }
  }
}

Exemplo de anotação Swagger:

Organização de pastas

Use nomes de pastas descritivos para organizar seus endpoints de forma lógica. Isso melhora a navegação e ajuda os membros da equipe a encontrar endpoints rapidamente.

Status do endpoint

Verifique o status do endpoint usando o campo x-apidog-status. Isso permite que você acompanhe o ciclo de vida de desenvolvimento de cada endpoint de API.

Valores de status disponíveis

Status	Descrição
designing	(Em design)
pending	(Pendente)
developing	(Em desenvolvimento)
integrating	(Em integração)
testing	(Em teste)
tested	(Testado)
released	(Lançado)
deprecated	(Obsoleto)
exception	(Exceção)
obsolete	(Obsoleto)
to be deprecated	(A ser descontinuado)

Exemplo:

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",     
            "x-apidog-status": "released"
        }
    }
}

Exemplo de anotação Swagger:

Acompanhamento de status

O status do endpoint ajuda as equipes a coordenar esforços de desenvolvimento e entender quais APIs estão prontas para uso em produção.

Mantenedor

Especifique o mantenedor de um endpoint usando o campo x-apidog-maintainer. Seu valor é o apelido ou nome de usuário do usuário do Apidog dentro da equipe.

Exemplo:

"paths": {
    "/pets": {
        "post": {
            ...   
            "x-apidog-maintainer": "david"
        }
    }
}

Exemplo de anotação Swagger:

Importante

O valor do mantenedor deve corresponder ao nome de usuário ou apelido de um membro existente da equipe no Apidog para atribuição adequada.

Extensões da especificação OpenAPI do Apidog

Especificar a pasta à qual um endpoint pertence#

Status do endpoint#

Valores de status disponíveis#

Mantenedor#

Especificar a pasta à qual um endpoint pertence

Status do endpoint

Valores de status disponíveis

Mantenedor