Extensiones de la especificación OpenAPI de Apidog

Apidog admite extensiones personalizadas de la especificación OpenAPI/Swagger que mejoran las capacidades de diseño y gestión de API. Estas extensiones le permiten especificar metadatos adicionales para sus endpoints de API, como la organización en carpetas, el estado del endpoint y la información del responsable de mantenimiento.

Esta guía de referencia documenta las extensiones personalizadas x-apidog-* que se pueden utilizar en sus especificaciones OpenAPI/Swagger para integrarse sin problemas con las funciones de Apidog.

Especificar la carpeta a la que pertenece un endpoint

Apidog dará prioridad al uso del campo x-apidog-folder para organizar los endpoints. Si este campo no existe, utilizará el primer valor del campo tags.

Utilice barras diagonales / para separar carpetas de varios niveles. Tenga en cuenta que tanto la barra invertida \ como la barra diagonal / son caracteres especiales que requieren escape. Para representar el carácter de barra diagonal /, utilice \/, y para representar el carácter \, utilice \\.

Ejemplo:

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

Ejemplo de anotación Swagger:

Organización de carpetas

Utilice nombres de carpetas descriptivos para organizar sus endpoints de forma lógica. Esto mejora la navegación y ayuda a los miembros del equipo a encontrar endpoints rápidamente.

Estado del endpoint

Compruebe el estado del endpoint mediante el campo x-apidog-status. Esto le permite realizar un seguimiento del ciclo de vida de desarrollo de cada endpoint de API.

Valores de estado disponibles

Estado	Descripción
designing	(Designing)
pending	(Pending)
developing	(Developing)
integrating	(Integrating)
testing	(Testing)
tested	(Tested)
released	(Released)
deprecated	(Deprecated)
exception	(Exception)
obsolete	(Obsolete)
to be deprecated	(To be Deprecated)

Ejemplo:

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

Ejemplo de anotación Swagger:

Seguimiento de estado

El estado del endpoint ayuda a los equipos a coordinar los esfuerzos de desarrollo y a comprender qué API están listas para su uso en producción.

Responsable de mantenimiento

Especifique el responsable de mantenimiento de un endpoint mediante el campo x-apidog-maintainer. Su valor es el apodo o nombre de usuario del usuario de Apidog dentro del equipo.

Ejemplo:

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

Ejemplo de anotación Swagger:

Importante

El valor del responsable de mantenimiento debe coincidir con el nombre de usuario o apodo de un miembro existente del equipo en Apidog para que la asignación sea correcta.

Extensiones de la especificación OpenAPI de Apidog

Especificar la carpeta a la que pertenece un endpoint#

Estado del endpoint#

Valores de estado disponibles#

Responsable de mantenimiento#

Especificar la carpeta a la que pertenece un endpoint

Estado del endpoint

Valores de estado disponibles

Responsable de mantenimiento