Documentación pública · v1.0.0

03 · OpenAPI 3.1

MSD-03-OAPI · OpenAPI 3.1

Una única especificación. Todo el ecosistema.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Definir OpenAPI 3.1 como la fuente oficial del contrato técnico de Roustix.

Toda la documentación interactiva, los SDK oficiales, el CLI, las colecciones Postman, el API Explorer y futuras herramientas se generan a partir de esta especificación.

Audiencia	Documento
Personas	MAG — describe la API
Herramientas	OpenAPI — describe exactamente la misma API

→ MSD-02 · Developer Portal

1 · Filosofía

OpenAPI no es documentación adicional.

Es la representación machine-readable del contrato MAG.

Toda herramienta debe consumir OpenAPI.
Nunca redefinir endpoints manualmente en SDK, Explorer o colecciones.

2 · Fuente única de verdad

MAG
      │
      ▼
OpenAPI 3.1
      │
 ┌────┼────┬─────┬─────┐
 ▼    ▼    ▼     ▼     ▼
SDK Explorer CLI Postman Docs

Regla	Descripción
MAG → OpenAPI	MAG define el contrato; OpenAPI lo codifica
OpenAPI → herramientas	SDK, Explorer, CLI y Postman se generan
Sin bifurcación	Una sola especificación por versión API

3 · Ubicación

Artefacto	Ruta
Repositorio	`docs/api/openapi.v1.yaml`
Runtime JSON	`GET /api/v1/openapi.json`
Runtime YAML	`GET /api/v1/openapi.yaml`
Portal	`/msd/openapi` → especificación en vivo

python run.py
curl http://127.0.0.1:5000/api/v1/openapi.json

4 · Versión

openapi: 3.1.0
info:
  title: Roustix API
  version: 1.0.0

Campo	Significado
`openapi`	Versión del formato OpenAPI (3.1.0)
`info.version`	Versión del contrato API (alineada a MAG v1.0)

5 · Organización

Estructura de openapi.v1.yaml:

openapi.v1.yaml
├── info
├── servers
├── security
├── tags
├── paths
└── components
    ├── schemas
    ├── responses
    ├── parameters
    └── securitySchemes

Cada sección tiene responsabilidad única — sin duplicar definiciones fuera de components/.

6 · Relación con MAG

Cada capítulo MAG alimenta una parte de OpenAPI.

MAG	OpenAPI
MAG-02 · JWT	`securitySchemes` · `/auth/login`
MAG-03 · Multi-tenant	Contexto tenant en schemas · `/me`
MAG-04 · Recursos	`paths` · tags por módulo
MAG-05 · Convenciones	Naming · `snake_case` en schemas
MAG-06 · Errores	`components/responses` · `ErrorResponse`
MAG-07 · Versionado	`info.version` · `openapi.v1.yaml`
MAG-08 · Webhooks	Roadmap · callbacks

Regla: si un endpoint existe en MAG-04, debe existir en OpenAPI antes de publicarse.

7 · Servidores

servers:
    description: Producción
  - url: http://127.0.0.1:5000/api/v1
    description: Desarrollo local

Los clientes y el API Explorer seleccionan servidor según entorno.

8 · Seguridad

JWT Bearer — referencia directa a MAG-02.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Rutas públicas (login) declaran security: [].

9 · Tags

Tags oficiales alineados a módulos MAG-04:

Tag	Módulo
Authentication	`auth` · `/me`
Maintenance	`maintenance/*`
Inventory	`inventory/*`
Purchasing	`purchasing/*`
Sales	`sales/*`
CRM	`crm/*`
Admin	`admin/*`

Cada operación en paths usa exactamente un tag principal.

10 · Schemas

Todos los modelos públicos viven en components/schemas.

Schema	Descripción
Asset	Activo de mantenimiento
WorkOrder	Orden de trabajo
Product	Producto de inventario
User	Usuario
ErrorResponse	Formato error MAG-06
Pagination	`meta.pagination`

Ejemplo — Asset:

Asset:
  type: object
  properties:
    asset_id:
      type: integer
    asset_code:
      type: string
    name:
      type: string
    status:
      type: string
      enum: [operational, maintenance, inactive]
    critical:
      type: boolean

Recursos planificados pueden incluir x-mag-status: planned hasta implementación en código.

11 · Responses

Respuestas reutilizables en components/responses — alineadas con MAG-06:

Response	HTTP	Código ejemplo
Unauthorized	401	`UNAUTHORIZED`
Forbidden	403	`FORBIDDEN`
NotFound	404	`RESOURCE_NOT_FOUND`
ValidationError	422	`VALIDATION_ERROR`
RateLimitExceeded	429	`RATE_LIMIT_EXCEEDED`
InternalError	500	`INTERNAL_ERROR`

Todas referencian el schema ErrorResponse.

12 · Generación

OpenAPI genera automáticamente:

Artefacto	Capítulo MSD
SDK Python	MSD-04
SDK JavaScript	MSD-04
SDK PHP	MSD-04
API Explorer	MSD-06
Postman	MSD-08
Insomnia	MSD-08

Herramientas previstas: OpenAPI Generator · Speakeasy · openapi-typescript

13 · Validación

Pipeline CI (objetivo MSD v1.0):

OpenAPI
   │
   ▼
Spectral        ← reglas MAG-05 / MAG-06
   │
   ▼
Prism           ← mock / contract tests
   │
   ▼
CI
   │
   ▼
Deploy

El contrato siempre debe validar antes del despliegue.

Herramienta	Rol
Spectral	Lint del YAML · naming · responses
Prism	Mock server · contract testing

Estado: pipeline documentado · CI en roadmap MSD v1.0.

14 · Compatibilidad

OpenAPI sigue exactamente MAG-07:

openapi.v1.yaml  →  API v1
openapi.v2.yaml  →  API v2   (futuro)

Nunca mezclar versiones en un mismo archivo.

Cambio	Acción
Compatible en v1	Patch `info.version` · mismo `openapi.v1.yaml`
Breaking	Nuevo archivo `openapi.v2.yaml`

15 · Roadmap OpenAPI

Capacidad	Estado
Webhooks en spec	📋 MAG-08 · callbacks OpenAPI 3.1
Callbacks	📋 Eventos outbound
AsyncAPI	Roadmap · eventos asíncronos
GraphQL Gateway	Evaluación

16 · Buenas prácticas

#	Regla
1	Nunca editar la documentación HTML de referencia directamente
2	OpenAPI es la fuente oficial para herramientas
3	MAG explica; OpenAPI describe
4	Todo SDK proviene de OpenAPI
5	Todo endpoint debe existir en OpenAPI antes de publicarse
6	Reutilizar `components/responses` — no duplicar errores
7	Mantener `openapi.v1.yaml` sincronizado con MAG-04

Filosofía del capítulo

OpenAPI convierte el contrato de Roustix en un estándar consumible por personas y herramientas. Es la fuente única de verdad sobre la API y el punto de partida de todo el ecosistema de desarrollo.

Así como MAG-04 fue el documento central del, MSD-03 es el documento central del.

← 02 · Portal 04 · SDK →