CLI para trabajar con contratos OpenAPI 3: modularizar, generar bundle, documentación Markdown y convertir a Swagger 2.0.
npm install @apifactory/openapi-builderbash
npm install -g @apifactory/openapi-builder
`
O como dependencia del proyecto:
`bash
npm install --save-dev @apifactory/openapi-builder
`
🚀 Uso
$3
Divide un OpenAPI monolítico en estructura modular con corrección de referencias y deduplicación.
`bash
openapi-builder modularize --build ./api/petstore-oas3.0.0.yaml
`
Salida: ./src/ con estructura modular (main.yaml + components/ + paths/)
$3
Consolida estructura modular en bundle OpenAPI 3.
`bash
openapi-builder bundle -i ./src/main.yaml -o ./dist/bundle.yaml
`
Opciones:
- -i, --input: Entrypoint modular (default: ./src/main.yaml)
- -o, --output: Ruta del bundle (default: ./dist/bundle.yaml)
$3
Genera documentación Markdown desde el bundle.
`bash
openapi-builder docs -i ./dist/bundle.yaml -o ./docs/api.md
`
Opciones:
- -i, --input: Bundle OpenAPI (default: ./dist/bundle.yaml)
- -o, --output: Ruta Markdown (default: ./docs/api.md)
$3
Convierte OpenAPI 3.x a Swagger 2.0.
`bash
openapi-builder swagger2 -i ./dist/bundle.yaml -o ./dist/swagger2.yaml
`
Opciones:
- -i, --input: Bundle OpenAPI 3 (default: ./dist/bundle.yaml)
- -o, --output: Ruta Swagger 2 (default: ./dist/swagger2.yaml)
📁 Estructura de Salida
`
proyecto/
├── src/ # Estructura modular (modularize)
│ ├── main.yaml
│ ├── components/
│ └── paths/
├── dist/ # Outputs consolidados
│ ├── bundle.yaml # Bundle OpenAPI 3 (bundle)
│ └── swagger2.yaml # Swagger 2.0 (swagger2)
└── docs/ # Documentación
└── api.md # Docs Markdown (docs)
`
⚙️ Configuración
Los comandos pueden personalizarse mediante archivos YAML en ./config/:
- config/modularize.yaml: Configuración de modularización
- config/bundle.yaml: Opciones de bundling
- config/swagger2.yaml: Configuración de conversión
- config/logging.yaml: Configuración de logging
🏗️ Arquitectura
El proyecto sigue Clean Architecture con capas claramente definidas:
`
bin/
├── interface/ # CLI, menús, presenters
├── application/ # Use cases, ports
├── domain/ # Entities, services, value objects
└── infrastructure/ # Adapters (Redocly, Widdershins, etc.)
``