Appearance
Documentacion OpenAPI del Modulo de Membresias
Modulo: Membresias Tipo: Resource Estado: Implementado Fecha: 2026-01-27
Descripcion
Problema que resuelve
El modulo de membresias expone multiples recursos y operaciones a traves de su interfaz de programacion. Sin documentacion estructurada, los consumidores de la interfaz enfrentan los siguientes problemas:
- Falta de referencia: Los desarrolladores y sistemas que consumen la interfaz de membresias no tienen una referencia unica y actualizada de los recursos disponibles
- Desconocimiento de formatos: Los formatos de datos de entrada y salida no estan formalmente documentados, generando errores de integracion
- Dificultad para descubrir funcionalidades: Sin un catalogo estructurado, es dificil identificar todos los recursos y operaciones disponibles en el modulo
- Documentacion desactualizada: La documentacion manual tiende a desactualizarse a medida que el modulo evoluciona
Solucion implementada
Se implementa un sistema de generacion automatica de documentacion bajo el estandar OpenAPI 3.0.3, que produce una especificacion completa del modulo de membresias incluyendo todos sus recursos, formatos de datos, ejemplos de uso y tipos de error.
Valor de negocio
- Referencia unica y confiable: Toda la documentacion de la interfaz del modulo se genera desde una fuente unica
- Integracion facilitada: Los consumidores pueden consultar la especificacion para implementar integraciones correctamente
- Descubrimiento de funcionalidades: El catalogo de recursos permite identificar rapidamente las capacidades del modulo
- Consistencia: La generacion desde el codigo fuente garantiza que la documentacion refleja la implementacion real
Contexto del sistema
La documentacion OpenAPI se genera para todo el modulo de membresias, cubriendo los siguientes recursos de negocio:
- Miembros (socios/contribuyentes)
- Disciplinas (actividades deportivas)
- Categorias de membresia
- Tipos de relacion familiar
- Grupos familiares
- Operaciones masivas (bulk)
- Facturacion por lotes
Proceso de Negocio
Generacion de la especificacion
La especificacion OpenAPI se genera de forma modular: cada recurso del modulo produce su propia seccion de la especificacion, y luego se consolidan en un documento unico.
Recursos documentados
| Recurso | Descripcion | Operaciones cubiertas |
|---|---|---|
| Miembros | Gestion de socios y contribuyentes | Listado, consulta, alta, modificacion, baja, reactivacion |
| Disciplinas | Catalogo de actividades deportivas | Listado, consulta, alta, modificacion, eliminacion |
| Categorias | Clasificaciones de membresia | Listado, consulta, alta, modificacion, eliminacion |
| Tipos de relacion | Roles familiares | Listado, consulta, alta, modificacion, eliminacion |
| Grupos familiares | Agrupaciones de miembros | Listado, consulta, alta de miembros, modificacion de miembros, eliminacion de miembros |
| Operaciones masivas | Asignaciones y cambios en lote | Asignacion masiva de categorias, disciplinas, productos |
| Facturacion por lotes | Facturacion periodica masiva | Ejecutar facturacion, consultar resultados, re-facturar |
Contenido de la especificacion por recurso
Cada recurso documentado incluye:
| Seccion | Descripcion |
|---|---|
| Esquemas de datos de entrada | Formatos de los datos que se envian al sistema |
| Esquemas de datos de salida | Formatos de los datos que devuelve el sistema |
| Operaciones disponibles | Listado de operaciones con su descripcion |
| Parametros de consulta | Filtros, paginacion, ordenamiento, includes |
| Respuestas de exito | Formatos de respuesta para operaciones exitosas |
| Respuestas de error | Formatos de respuesta para errores de validacion, no encontrado, etc. |
| Ejemplos de uso | Valores de ejemplo para cada campo y operacion |
Esquemas comunes
La especificacion incluye esquemas reutilizados por multiples recursos:
| Esquema comun | Descripcion | Usado por |
|---|---|---|
| Respuesta de error | Formato estandar de respuesta ante errores | Todos los recursos |
| Error de validacion | Formato de errores de validacion de datos | Operaciones de escritura |
| Localidad | Datos de ubicacion geografica | Miembros (domicilio) |
| Vendedor | Datos de vendedor asociado | Miembros (relacion comercial) |
| Condicion de IVA | Datos de condicion fiscal | Miembros (facturacion) |
| IIBB | Datos de ingresos brutos | Miembros (facturacion) |
| Producto con precio | Producto con listas de precio y ajustes | Categorias, miembros (productos asociados) |
Parametros de consulta estandarizados
| Parametro | Descripcion | Recursos que lo soportan |
|---|---|---|
| Include | Incluir relaciones asociadas | Miembros, categorias, disciplinas |
| Indice de pagina | Pagina actual para paginacion | Miembros |
| Tamano de pagina | Cantidad de registros por pagina | Miembros |
| Filtro global | Busqueda por texto libre | Miembros |
| Filtro por estado | Filtrar por estado activo/inactivo | Miembros |
| Ordenamiento | Columna y direccion de ordenamiento | Miembros |
| Filtro por columna | Filtros especificos por columna | Miembros |
Frontend (Perspectiva de Usuario)
Vistas
Vista de documentacion interactiva
- La especificacion OpenAPI se puede visualizar con herramientas estandar del ecosistema (SwaggerUI, Redoc)
- La documentacion es consultable por desarrolladores y equipos de integracion
- Permite explorar recursos, ver formatos y probar operaciones
Interacciones del usuario
- Consultar especificacion completa: El usuario puede acceder a la documentacion completa del modulo
- Consultar recurso especifico: El usuario puede acceder a la documentacion de un recurso individual
- Ver listado de recursos disponibles: El usuario puede obtener el catalogo de todos los recursos del modulo
- Explorar esquemas de datos: El usuario puede consultar los formatos de datos de entrada y salida
- Revisar ejemplos: El usuario puede ver valores de ejemplo para cada operacion
Permisos
| Permiso | Descripcion | Acciones permitidas |
|---|---|---|
| Acceso a documentacion | Acceso a la especificacion del modulo | Consultar documentacion |
Estados de UI
- Documentacion cargada: La especificacion se muestra correctamente con todos los recursos
- Recurso no encontrado: Si se solicita un recurso que no existe, se muestra error
- Error de generacion: Si hay un problema al generar la especificacion, se muestra mensaje de error
Backend (Perspectiva de Datos de Negocio)
Entidades de negocio involucradas
Especificacion OpenAPI del Modulo
Documento que describe la interfaz completa del modulo de membresias.
| Dato de negocio | Descripcion |
|---|---|
| Version de la especificacion | Version del estandar OpenAPI utilizado (3.0.3) |
| Titulo | Nombre del modulo documentado |
| Descripcion | Descripcion general del modulo |
| Version del modulo | Version actual de la interfaz |
| Recursos | Listado de recursos disponibles |
| Esquemas | Formatos de datos de entrada y salida |
| Seguridad | Esquema de autenticacion requerido (JWT Bearer) |
Recurso Documentado
Cada recurso del modulo tiene su propia seccion de documentacion.
| Dato de negocio | Descripcion |
|---|---|
| Nombre del recurso | Identificador del recurso (miembros, categorias, etc.) |
| Etiqueta | Nombre visible del recurso |
| Descripcion | Descripcion del recurso y su proposito |
| Operaciones | Listado de operaciones disponibles para el recurso |
| Esquemas de datos | Formatos de entrada y salida especificos del recurso |
Relaciones de negocio
- La especificacion del modulo contiene multiples recursos documentados
- Cada recurso define sus propios esquemas de datos y operaciones
- Existen esquemas comunes reutilizados por multiples recursos
- La seguridad (autenticacion JWT) aplica globalmente a todos los recursos
Validaciones de negocio
| Validacion | Descripcion |
|---|---|
| Recurso existente | Al consultar un recurso especifico, debe existir en el catalogo |
| Especificacion coherente | Los esquemas referenciados deben existir en la seccion de componentes |
Reglas de Negocio
RN-001: Especificacion generada desde codigo fuente
Descripcion: La especificacion OpenAPI se genera programaticamente desde los servicios de documentacion de cada recurso, garantizando que refleja la implementacion real.
Condicion: Se solicita la especificacion del modulo o de un recurso.
Accion:
- Cada recurso genera su propia seccion de la especificacion
- Se consolidan todas las secciones en un documento unico
- Se incluyen esquemas comunes reutilizables
- Se aplica el esquema de seguridad global
RN-002: Modularidad de la documentacion
Descripcion: La documentacion es modular: se puede consultar la especificacion completa del modulo o la de un recurso individual. Ambas son especificaciones OpenAPI validas e independientes.
Condicion: Se solicita documentacion.
Accion:
- Si se solicita el modulo completo: consolidar todas las secciones de recursos
- Si se solicita un recurso individual: generar solo la especificacion de ese recurso
- Ambas respuestas son especificaciones OpenAPI 3.0.3 validas
RN-003: Catalogo de recursos descubrible
Descripcion: El sistema expone un catalogo con todos los recursos disponibles en el modulo, permitiendo descubrir funcionalidades sin conocimiento previo.
Condicion: Se solicita el listado de recursos disponibles.
Accion:
- Devolver la lista de todos los recursos documentados del modulo
- Cada recurso se identifica por su nombre unico
Casos de Uso
CU-001: Consultar documentacion completa del modulo
Actor: Desarrollador / Equipo de integracion
Precondiciones:
- Usuario autenticado con acceso a la documentacion
- El modulo de membresias esta activo
Flujo principal:
- El usuario solicita la especificacion completa del modulo de membresias
- El sistema genera la especificacion consolidando todos los recursos
- El sistema devuelve un documento OpenAPI 3.0.3 con:
- Informacion general del modulo
- Todos los recursos y sus operaciones
- Todos los esquemas de datos
- Esquema de seguridad
- El usuario puede visualizar la especificacion con herramientas estandar
Postcondiciones:
- El usuario tiene acceso a la documentacion completa de la interfaz del modulo
CU-002: Consultar documentacion de un recurso especifico
Actor: Desarrollador / Equipo de integracion
Precondiciones:
- Usuario autenticado con acceso a la documentacion
- El recurso solicitado existe en el modulo
Flujo principal:
- El usuario consulta el catalogo de recursos disponibles
- El usuario selecciona un recurso especifico (ejemplo: "miembros")
- El sistema genera la especificacion solo para ese recurso
- El usuario obtiene la documentacion enfocada en el recurso seleccionado
Postcondiciones:
- El usuario tiene la documentacion detallada del recurso seleccionado
Flujos alternativos:
- Recurso no encontrado: Si el recurso no existe en el catalogo, el sistema informa del error
CU-003: Descubrir funcionalidades del modulo
Actor: Desarrollador / Equipo de integracion
Precondiciones:
- Usuario autenticado con acceso a la documentacion
Flujo principal:
- El usuario solicita el listado de recursos disponibles
- El sistema devuelve: miembros, disciplinas, categorias, tipos de relacion, grupos familiares, operaciones masivas, facturacion por lotes
- El usuario identifica los recursos relevantes para su integracion
- El usuario consulta la documentacion de los recursos de interes
Postcondiciones:
- El usuario conoce todas las capacidades del modulo de membresias
Consideraciones
Seguridad
- La documentacion requiere autenticacion JWT para acceder
- No se expone informacion sensible en los ejemplos (se usan datos ficticios)
- El esquema de seguridad documenta que todas las operaciones requieren JWT Bearer
Auditoria
- El acceso a la documentacion no genera registros de auditoria (es informacion de referencia)
Rendimiento
- La generacion de la especificacion es una operacion ligera que no consulta la base de datos
- La especificacion completa del modulo se genera en memoria consolidando las secciones de cada recurso
Dependencias
Funcionalidades relacionadas
- Todos los recursos del modulo de membresias: Cada recurso contribuye su seccion a la especificacion
- Autenticacion JWT: Esquema de seguridad documentado en la especificacion
- Herramientas de visualizacion OpenAPI: La especificacion es compatible con SwaggerUI, Redoc y otras herramientas estandar
Criterios de Aceptacion
- [x] AC-001: La especificacion se genera en formato OpenAPI 3.0.3 valido
- [x] AC-002: Se documentan todos los recursos del modulo: miembros, disciplinas, categorias, tipos de relacion, grupos familiares, operaciones masivas, facturacion por lotes
- [x] AC-003: Cada recurso incluye esquemas de datos de entrada y salida
- [x] AC-004: Cada recurso incluye sus operaciones con descripcion
- [x] AC-005: Se incluyen ejemplos de valores para los campos
- [x] AC-006: Se documentan las respuestas de exito y error
- [x] AC-007: Se incluyen esquemas comunes reutilizables (errores, localidad, vendedor, etc.)
- [x] AC-008: Se puede consultar la especificacion completa del modulo
- [x] AC-009: Se puede consultar la especificacion de un recurso individual
- [x] AC-010: Se puede obtener el catalogo de recursos disponibles
- [x] AC-011: El esquema de seguridad JWT Bearer esta documentado
Notas Adicionales
Estandar OpenAPI 3.0.3
La especificacion sigue el estandar OpenAPI 3.0.3 (anteriormente conocido como Swagger), que es el estandar de la industria para documentar interfaces de programacion. Este estandar permite:
- Visualizacion interactiva con herramientas como SwaggerUI
- Generacion de clientes en multiples lenguajes de programacion
- Validacion automatica de las solicitudes contra los esquemas definidos
- Importacion en herramientas de pruebas como Postman
Recursos documentados en detalle
El modulo documenta 7 recursos principales que cubren toda la funcionalidad de membresias:
- Miembros: CRUD completo con filtros avanzados, paginacion, enriquecimiento y baja/reactivacion
- Disciplinas: CRUD completo de actividades deportivas
- Categorias: CRUD completo de clasificaciones de membresia con producto asociado
- Tipos de relacion: CRUD completo de roles familiares
- Grupos familiares: Gestion de agrupaciones con alta, modificacion y baja de miembros
- Operaciones masivas: Asignacion en lote de categorias, disciplinas y productos
- Facturacion por lotes: Ejecucion de facturacion masiva con resultados y re-facturacion
Historial de Cambios
| Fecha | Version | Autor | Descripcion |
|---|---|---|---|
| 2026-01-27 | 1.0 | Sistema | Documentacion de funcionalidad implementada |