Comprender la estructura de la documentación

Al generar la documentación de Swagger, el sistema « Sterling™ Order Management » crea una estructura de carpetas bien organizada que contiene especificaciones JSON, páginas HTML interactivas, un archivo de índice principal y un índice de búsqueda.

La documentación se encuentra en runtime/xapidocs/swaggerdoc/.

Carpeta JSON (swaggerdoc/JSON/)

La carpeta JSON contiene archivos con especificaciones técnicas de la API, como ycp.json, ycd.json, y omp.json. Estas definiciones de API legibles por máquina se utilizan para herramientas y procesos de automatización.

Casos de uso

  • Genera código de cliente en Java, Python, JavaScript, y otros lenguajes.
  • Integrarse con plataformas de gestión de API.
  • Configura las pruebas automatizadas.

Estos archivos los utilizan desarrolladores, ingenieros de control de calidad y especialistas en integración.

Carpeta HTML (swaggerdoc/HTML/)

La carpeta HTML contiene páginas web interactivas para cada grupo de API, como ycp.html, ycd.html, y omp.html. Estas páginas ofrecen documentación fácil de leer con funciones interactivas.

Características principales

  • Secciones desplegables : navega fácilmente por las API.
  • Detalles completos : consulta las descripciones de los campos, las etiquetas obligatorias y los tipos de datos.
  • Ejemplos : Revisa las solicitudes y respuestas de muestras.

Estas páginas están dirigidas a desarrolladores, analistas de negocios, gestores de proyectos, redactores técnicos y cualquier persona que necesite comprender las API.

index.html archivo (swaggerdoc/index.html)

El index.html archivo es el punto de acceso principal y ofrece funciones de navegación y búsqueda.

Características

  • Botones para cada grupo de API
  • Barra de búsqueda global para encontrar API en todos los grupos
  • Interfaz sencilla que facilita la navegación

Cómo se utiliza

  • Haz clic en el botón de un grupo para ver sus API.
  • Utiliza la barra de búsqueda para encontrar API específicas al instante.
  • Añade esta página a tus favoritos como punto de partida.

api-index.js archivo (swaggerdoc/api-index.js)

El api-index.js archivo es un índice de búsqueda generado automáticamente que permite el funcionamiento de la función de búsqueda en tiempo real. Contiene una lista completa de todas las API con sus nombres, métodos, grupos y enlaces de navegación.

Nota: El índice de búsqueda se actualiza automáticamente al volver a generar la documentación. No es necesario editarlo manualmente.

Mejores prácticas

Para sacar el máximo partido a la documentación de Swagger, sigue estas recomendaciones:

  • Empieza por index.html como punto de partida principal.
  • Utiliza la función de búsqueda para encontrar rápidamente las API en todos los grupos.
  • Importa archivos JSON a Postman o herramientas similares para realizar pruebas de API.
  • Añade a tus favoritos las páginas HTML de los grupos de API que utilizas con más frecuencia para acceder a ellas rápidamente.
  • Comparte la documentación URL con tu equipo de desarrollo.

Para obtener más información, consulta la especificación de OpenAPI y Swagger UI.