Extensões da Especificação OpenAPI do Apidog

O Apidog suporta extensões personalizadas da especificação OpenAPI/Swagger que melhoram as capacidades de conceção e gestão de APIs. Estas extensões permitem-lhe especificar metadados adicionais para os endpoints da sua API, tais como a organização por pastas, o estado do endpoint e as informações do responsável pela manutenção.

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

Especificar a Pasta à Qual um Endpoint Pertence

O Apidog dará prioridade à utilização do campo x-apidog-folder para organizar endpoints. Se este campo não existir, utilizará o primeiro valor no campo tags.

Utilize barras / para separar pastas de vários níveis. Note que tanto a barra invertida \ como a barra normal / são caracteres especiais que requerem escape. Para representar o carácter de barra normal /, utilize \/; para representar o carácter \, utilize \\.

Exemplo:

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

Exemplo de Anotação Swagger:

Organização de Pastas

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

Estado do Endpoint

Verifique o estado do endpoint utilizando o campo x-apidog-status. Isto permite-lhe acompanhar o ciclo de vida de desenvolvimento de cada endpoint de API.

Valores de Estado Disponíveis

Estado	Descrição
designing	(Em conceção)
pending	(Pendente)
developing	(Em desenvolvimento)
integrating	(Em integração)
testing	(Em teste)
tested	(Testado)
released	(Lançado)
deprecated	(Obsoleto)
exception	(Exceção)
obsolete	(Descontinuado)
to be deprecated	(A tornar-se obsoleto)

Exemplo:

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

Exemplo de Anotação Swagger:

Acompanhamento de Estado

O estado do endpoint ajuda as equipas a coordenar os esforços de desenvolvimento e a compreender que APIs estão prontas para utilização em produção.

Responsável pela Manutenção

Especifique o responsável pela manutenção de um endpoint utilizando o campo x-apidog-maintainer. O respetivo valor é a alcunha ou o nome de utilizador do utilizador do Apidog dentro da equipa.

Exemplo:

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

Exemplo de Anotação Swagger:

Importante

O valor do responsável pela manutenção deve corresponder ao nome de utilizador ou à alcunha de um membro existente da equipa no Apidog para uma atribuição correta.

Extensões da Especificação OpenAPI do Apidog

Especificar a Pasta à Qual um Endpoint Pertence#

Estado do Endpoint#

Valores de Estado Disponíveis#

Responsável pela Manutenção#

Especificar a Pasta à Qual um Endpoint Pertence

Estado do Endpoint

Valores de Estado Disponíveis

Responsável pela Manutenção