Version: 1.0
Fecha: 2026-04-15
Arquitecto: Carlos Alberto Torres Camargo
Establecer el procedimiento oficial y unico para consultar la documentacion OpenAPI/Swagger publicada por los microservicios backend de Nebula expuestos a traves del Gateway Simappe. Este documento garantiza que cualquier integrador, desarrollador frontend, QA o arquitecto pueda obtener el contrato vigente de un servicio sin depender del codigo fuente, siguiendo los controles de seguridad establecidos por la plataforma (OAuth2 + Bearer Token JWT).
Audiencia: Desarrolladores backend y frontend, QA, integradores externos, equipo de soporte tecnico.
Servicios cubiertos en esta primera version:
| Servicio | Context Path | Repositorio |
|---|---|---|
| Nebula Accounting Core | /nebula-accounting-core |
nebula-accounting-core |
| Nebula Masters | /nebula-masters |
nebula-masters |
El procedimiento aplica de forma identica al resto de microservicios
nebula-*que exponganspringdoc-openapi. Solo cambia elcontext-pathdel servicio.
+-------------+ 1. POST /login +------------------------+
| Cliente | -----------------------------> | simappe-oauth2-server |
| (curl, UI, | <----------------------------- | (Bearer Token JWT) |
| Postman) | 2. SimappeToken +------------------------+
+-------------+
|
| 3. GET /nebula-{servicio}/api-docs
| Authorization: Bearer {accessToken}
v
+--------------------+ +-------------------------+
| simappe-gateway | -----> | nebula-accounting-core |
| (valida JWT) | | nebula-masters |
+--------------------+ +-------------------------+
|
| springdoc-openapi
v
OpenAPI 3.1 JSON
Reglas clave:
api-docs o swagger-ui pasa por el Gateway (api-dev.centricasoluciones.com).simappe-oauth2-server y se valida en el Gateway via jwt-validate.| Entorno | URL Base Gateway |
|---|---|
| DEV | https://api-dev.centricasoluciones.com |
| QA | https://api-qa.centricasoluciones.com |
| PROD | https://api.centricasoluciones.com |
Los ejemplos de este documento usan DEV. Para QA o PROD basta con sustituir el host. Las credenciales de cada entorno son distintas y se gestionan por el equipo de plataforma; nunca se usan credenciales de DEV en QA/PROD ni viceversa.
Endpoint:
POST https://api-dev.centricasoluciones.com/simappe-oauth2-server/api/v1/login
Content-Type: application/json
Body:
{
"username": "dev@nebula",
"password": "Catcsoft@Simappe"
}
Ejemplo curl:
curl -X POST \
https://api-dev.centricasoluciones.com/simappe-oauth2-server/api/v1/login \
-H "Content-Type: application/json" \
-d '{
"username": "dev@nebula",
"password": "Catcsoft@Simappe"
}'
Respuesta (200 OK) - SimappeToken:
{
"accessToken": "eyJhbGciOiJSUzI1NiJ9...",
"refreshToken": "eyJhbGciOiJSUzI1NiJ9...",
"expiresIn": 3600,
"sessionId": "f3e1a9c0-..."
}
| Campo | Tipo | Descripcion |
|---|---|---|
accessToken |
String (JWT) | Token Bearer a usar en el header Authorization. |
refreshToken |
String (JWT) | Permite renovar el accessToken sin volver a enviar credenciales. |
expiresIn |
long (segundos) | Tiempo de vida del accessToken. |
sessionId |
UUID | Identificador unico de la sesion (extraido del JWT). |
Errores comunes:
| Codigo | Causa | Accion |
|---|---|---|
| 401 | Credenciales invalidas | Verificar usuario y password del entorno. |
| 403 | Usuario bloqueado o sin permisos | Solicitar revision al equipo de plataforma. |
| 503 | OAuth2 server caido | Validar estado en simappe-eureka-server. |
accessTokenPara uso en consola Linux/Mac (jq requerido):
TOKEN=$(curl -s -X POST \
https://api-dev.centricasoluciones.com/simappe-oauth2-server/api/v1/login \
-H "Content-Type: application/json" \
-d '{"username":"dev@nebula","password":"Catcsoft@Simappe"}' \
| jq -r '.accessToken')
echo "Bearer $TOKEN"
En Postman use un script en la pestana Tests del request de login:
pm.environment.set("accessToken", pm.response.json().accessToken);
Cada servicio expone el contrato OpenAPI 3.1 en la ruta /api-docs bajo su context-path.
curl -X GET \
https://api-dev.centricasoluciones.com/nebula-accounting-core/api-docs \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
curl -X GET \
https://api-dev.centricasoluciones.com/nebula-masters/api-docs \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Respuesta esperada: documento OpenAPI 3.1 (JSON) con info, servers, paths, components.schemas, components.securitySchemes, etc.
Para guardar el contrato a archivo:
curl -s -X GET \
https://api-dev.centricasoluciones.com/nebula-accounting-core/api-docs \
-H "Authorization: Bearer $TOKEN" \
| jq '.' > nebula-accounting-core-openapi.json
Para visualizar el contrato (Swagger UI, Postman o editor externo), continuar con la seccion 6 — VISUALIZACION Y CONSUMO DEL CONTRATO OPENAPI.
Una vez obtenido el JSON del paso 5.3, existen tres formas oficiales de visualizar y trabajar con el contrato. Elija la que corresponda al objetivo:
| Objetivo | Herramienta recomendada |
|---|---|
| Probar endpoints manualmente con un solo clic | Swagger UI embebido (6.1) |
| Construir colecciones, automatizar tests, compartir requests | Postman (6.2) |
| Revisar el contrato sin tener acceso al Gateway / sin token | Swagger Editor publico (6.3) |
| Servicio | URL Swagger UI |
|---|---|
| Nebula Accounting Core | https://api-dev.centricasoluciones.com/nebula-accounting-core/swagger-ui.html |
| Nebula Masters | https://api-dev.centricasoluciones.com/nebula-masters/swagger-ui.html |
Procedimiento desde el navegador:
bearerAuth pegar el token con prefijo: Bearer eyJhbGciOiJSUzI1NiJ9....Authorization.Importante: el navegador tambien debe poder llegar al Gateway. Si la consulta se hace desde una red corporativa con restricciones, validar acceso a
api-dev.centricasoluciones.comantes de reportar fallas.
Postman permite generar automaticamente una coleccion completa con todos los endpoints, schemas y ejemplos a partir del JSON OpenAPI.
api-docs del servicio:
https://api-dev.centricasoluciones.com/nebula-accounting-core/api-docshttps://api-dev.centricasoluciones.com/nebula-masters/api-docsCollection (recomendado) o API si se planea versionar el contrato dentro de Postman.Tags (agrupa por @Tag de Swagger).Example (rellena con los example del schema).Si la URL requiere autenticacion (caso por defecto en Nebula), Postman pedira el token. Use Bearer Token en el dialogo de import o descargue primero el JSON con
curly use la opcion B.
> nebula-accounting-core-openapi.json)..json.Tras importar, configure el Bearer Token una sola vez para que aplique a todos los endpoints:
{{accessToken}} (variable de entorno).accessToken con el valor obtenido en 5.2.Type: Inherit auth from parent).En la coleccion -> pestana Pre-request Script:
const tokenExpiry = pm.environment.get("tokenExpiry");
if (!tokenExpiry || Date.now() > parseInt(tokenExpiry)) {
pm.sendRequest({
url: "https://api-dev.centricasoluciones.com/simappe-oauth2-server/api/v1/login",
method: "POST",
header: { "Content-Type": "application/json" },
body: { mode: "raw", raw: JSON.stringify({
username: pm.environment.get("username"),
password: pm.environment.get("password")
})}
}, (err, res) => {
const data = res.json();
pm.environment.set("accessToken", data.accessToken);
pm.environment.set("tokenExpiry", Date.now() + (data.expiresIn * 1000) - 60000);
});
}
Esto evita errores 401 cuando el token expira durante una sesion larga de pruebas.
Util cuando se quiere revisar el contrato sin desplegar el servicio o sin tener acceso al Gateway (ej. revision con un proveedor externo):
.json descargado.Precaucion de seguridad: no subir contratos de PROD a editores publicos si contienen ejemplos con datos sensibles. Para PROD use un Swagger Editor desplegado internamente o Postman offline.
Una vez que tenga el .json descargado, puede generar codigo cliente con openapi-generator-cli:
# Cliente TypeScript Angular para el frontend
openapi-generator-cli generate \
-i nebula-accounting-core-openapi.json \
-g typescript-angular \
-o ./generated/accounting-core-client
# Cliente Java para integraciones backend
openapi-generator-cli generate \
-i nebula-masters-openapi.json \
-g java \
-o ./generated/masters-client
| Situacion | Accion recomendada |
|---|---|
Token a punto de expirar (expiresIn agotado) |
Llamar POST /simappe-oauth2-server/api/v1/refresh con el refreshToken. |
| Token revocado / sesion cerrada | Repetir el flujo de login. |
| Cambio de tenant / compania | Usar POST /simappe-oauth2-server/api/v1/select-company para reemitir el JWT con tenantId. |
Antes de reportar que la documentacion OpenAPI no esta accesible, validar:
context-path correcto del servicio (/nebula-accounting-core o /nebula-masters).Authorization: Bearer <token> esta presente y sin saltos de linea.expiresIn).simappe-eureka-server o consultar /actuator/health si esta expuesto).$TOKEN) o secret managers (Vault, GitHub Secrets) en lugar de pegar el token en scripts./api-docs) y no el HTML del Swagger UI.| Caso | Procedimiento |
|---|---|
| Generar un cliente TypeScript para el frontend | Descargar api-docs con curl -> ejecutar openapi-generator-cli generate -i nebula-accounting-core-openapi.json -g typescript-angular. |
| Validar un contrato antes de un release | Comparar el api-docs actual contra el de la version anterior con openapi-diff. |
| Probar manualmente un endpoint nuevo | Abrir Swagger UI, autorizar, ejecutar Try it out sobre el endpoint en cuestion. |
| Reportar un bug de contrato | Adjuntar al ticket el JSON descargado de /api-docs y el endpoint afectado. |
springdoc en simappeconfig/{env}-config/application-common.yml.simappeconfig/{env}-config/simappe-gateway-server-{env}.yml.Guia Operativa - Arquitectura Nebula - v1.1
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.1.0 | 2026-04-15 | Carlos Torres | Se agrega seccion 6 (Visualizacion y consumo): import en Postman (URL/archivo, auth de coleccion, renovacion automatica de token), uso de Swagger Editor publico y generacion de clientes con openapi-generator-cli. |
| 1.0.0 | 2026-04-15 | Carlos Torres | Creacion del documento - procedimiento de consulta OpenAPI para nebula-accounting-core y nebula-masters. |