Swagger#
Swagger es nuestro modelo de API que permite conocer las estructuras y definiciones de cada microservicio de nuestra capa de servicios. Además, facilita la comprensión del uso de campos opcionales y obligatorios en la estructura JSON (DTO) necesaria para consumir cada servicio.
Como utilizar Swagger#
Los enlaces de acceso a Swagger están disponibles en el apartado de Entornos.
Al ingresar a Swagger, la pantalla inicial que verá será la siguiente:
1. En la parte superior derecha encontrará la URL a la que está apuntando la API.
2. En la parte superior izquierda encontrará una lista desplegable desde donde podrá seleccionar el grupo de definiciones que desea consultar.
3. En la parte inferior podrá visualizar los distintos servicios disponibles dentro del grupo de definiciones seleccionado.
4. Al tratarse de servicios API REST, podrá identificar el verbo HTTP (GET, POST, PUT, DELETE, etc.) con el que se debe consumir cada servicio.
5. También podrá ver el complemento de la URL necesario para consumir el servicio seleccionado.
Note
Las palabras entre llaves { userId } indican los parámetros que deben ser ingresados para consumir el servicio.
6. Para obtener información más detallada, haga clic en el ícono de flecha hacia abajo para desplegar el contenido del servicio.
7. Al desplegar la información del servicio, se mostrará la siguiente vista:
8. Encontrará información detallada sobre los parámetros requeridos para consumir el servicio, así como indicaciones en caso de que no se requieran parámetros.
9. Debajo de los parámetros, encontrará la estructura del body requerida para consumir el servicio, incluyendo el tipo de dato que corresponde a cada campo.
10. Al hacer clic en Schema, se mostrarán más detalles sobre el cuerpo de la solicitud (request body), incluyendo cuáles campos son obligatorios, identificados con un asterisco (*).
11. Al desplazarte hacia abajo, encontrarás las posibles respuestas que puede devolver nuestro servicio.
12. La primera respuesta que encontrarás es Success, la cual indica que el servicio fue consumido exitosamente y no se presentó ningún inconveniente.
13. A continuación, encontrarás la respuesta Bad Request, que indica que se produjo uno o varios errores al consumir el servicio.
14. Ambas estructuras de respuesta contienen los mismos campos y definiciones; sin embargo, solo se completan con la información relevante correspondiente a cada tipo de respuesta.
15. Al hacer clic en Schema, se mostrarán más detalles sobre la estructura del response, incluyendo sus campos y tipos de datos.
