Con el plugin de IDEA de Apidog o algunos plugins de Swagger, puedes generar fácilmente documentación de API a partir del código, resolviendo el problema de escribir la documentación desde cero.
Sin embargo, incluso después de que los endpoints estén escritos y la documentación generada, es posible que aún te sientas inseguro: ¿El diseño de la API es lo suficientemente bueno? ¿La documentación está estandarizada? ¿Hay áreas que se puedan mejorar aún más?
Especialmente en la colaboración en equipo, quieres que la documentación de tu API sea fácil de entender para tus compañeros de un vistazo. La claridad de los nombres y la exhaustividad de la información afectan directamente su experiencia al usar tus APIs.
Apidog ha lanzado recientemente varias funciones de IA para ayudarte a optimizar aún más la documentación de la API en esta etapa. Ya sea que estés mejorando los detalles de un endpoint existente o importando documentación de API existente de otro lugar, la IA puede ofrecer sugerencias prácticas.
A continuación, explicaremos cómo usar la IA en Apidog para crear una documentación de API más estandarizada. Antes de comenzar, asegúrate de haber actualizado Apidog a la última versión, habilitado las funciones de IA y configurado el modelo de IA.
Importación desde Documentación Existente
A veces, necesitas migrar documentación de API de otras fuentes a Apidog. Si la documentación está en un formato estándar, Apidog soporta de forma nativa múltiples métodos de importación: puedes generar documentación a partir de código a través del plugin de IDEA, importar especificaciones OpenAPI/Swagger o migrar desde otras herramientas como Postman.
Pero en algunos casos, tu documentación puede no estar en estos formatos estándar. Por ejemplo, el equipo documentó previamente los endpoints en Markdown, organizó las descripciones de los campos en Word, o encontró definiciones de endpoints en registros de chat o correos electrónicos. Introducir manualmente cada campo de estas fuentes no estándar en Apidog puede ser desalentador.
En esta situación, puedes usar la función Modificar esquema con IA para ayudar con la entrada de datos. Supón que tienes contenido Markdown como este:
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |Simplemente copia los parámetros y pregunta a la IA: "Convierte este contenido en parámetros de endpoint, asegurándote de identificar los tipos y los campos requeridos."
La IA detectará automáticamente los nombres de los campos, los tipos de datos, el estado requerido y las descripciones, para luego convertir todo al formato de esquema estándar de Apidog. Si se incluyen enumeraciones, la IA también las organizará en tipos de enumeración adecuados para ti.
La IA te Ayuda a Refinar los Detalles de la API
Después de importar la información básica, el siguiente paso es refinar los detalles.
Si no estás seguro del nombre de un campo, utiliza la función Nomenclatura con IA. La IA proporcionará sugerencias de nombres más precisas de acuerdo con las especificaciones del endpoint y las directrices de diseño de la API.
También puedes usar la IA para autocompletar las descripciones de los campos y obtener explicaciones más claras y completas.
La generación de datos simulados (mock data) es otra fortaleza de la IA. A menudo sabemos lo que representa un campo pero no estamos seguros de qué valores de ejemplo usar. La IA generará automáticamente datos de ejemplo razonables basándose en el tipo y la descripción del campo.
Verificación de Exhaustividad de la Documentación API: Evitando Omisiones
Cuando la documentación parece casi completa, es posible que aún te preguntes si falta alguna información clave. En este punto, utiliza la función Verificación de Exhaustividad de la Documentación API de Apidog para ver si algo se ha pasado por alto.
La IA escaneará tu documentación de API existente desde múltiples perspectivas para identificar información faltante o incompleta. Luego, genera un informe detallado que puntúa cada elemento de revisión, ayudándote a ver rápidamente dónde necesita mejorar tu documentación de API.
El informe no solo te dice qué hacer, sino que también explica el porqué. Por ejemplo, es posible que hayas documentado un formato de respuesta exitoso pero no los posibles escenarios de error; puedes tener descripciones básicas de campos pero carecer de restricciones de uso o requisitos de formato.
Puedes mejorar tu documentación de API siguiendo las sugerencias proporcionadas en el informe.
Verificación de Conformidad de Endpoints: Garantizando la Consistencia
Además de ser completa, la documentación de la API también debe estar bien estandarizada. Dentro de un mismo endpoint, la nomenclatura debe seguir un estilo consistente, los tipos de campo deben estar definidos de forma clara y correcta, y las estructuras de respuesta deben ser lógicas. Estos detalles desempeñan un papel clave para que tu documentación sea fácil de leer y mantener.
La función verificación de conformidad de endpoints de Apidog examina tu documentación desde múltiples ángulos. Por ejemplo, si algunos campos se nombran con verbos mientras que otros usan sustantivos, la IA señalará la inconsistencia y recomendará un estilo de nomenclatura unificado.
También verifica si las definiciones de campo siguen estándares consistentes, como evitar estilos de mayúsculas y minúsculas mixtos, el uso simultáneo de guiones bajos y camelCase, o abreviaturas inconsistentes, y luego proporciona sugerencias claras sobre cómo solucionar estos problemas.
Resumen
Crear documentación de API clara y estandarizada es esencial. Funciones como los casos de prueba generados por IA, dependen de la calidad de tu documentación; cuanto más completa y consistente sea, más precisos y útiles serán los casos de prueba generados.
No necesitas usar todas las funciones de IA a la vez ni reformar por completo tu flujo de trabajo actual.
Este es un proceso gradual. Puedes comenzar importando tu documentación existente y luego aplicar lentamente las funciones de IA para mejorarla y refinarla. Si no estás seguro de una sugerencia, puedes dejar las cosas como están y revisarlas más tarde cuando tengas más contexto.
Con el tiempo, desarrollarás naturalmente una mejor comprensión de los estándares de documentación de API. La IA no solo ayuda a solucionar problemas inmediatos, sino que también te ayuda a desarrollar mejores hábitos de documentación.