2.3 KiB
2.3 KiB
📚 Configuración Swagger UI para WSCONCILIA API
🎯 Integración de OpenAPI/Swagger en Laravel
1. Instalar L5-Swagger (Opcional)
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
2. Configurar Swagger UI Manual
Crear archivo public/swagger-ui.html:
<!DOCTYPE html>
<html>
<head>
<title>WSCONCILIA API Documentation</title>
<link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@4.15.5/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@4.15.5/swagger-ui-bundle.js"></script>
<script>
SwaggerUIBundle({
url: '/openapi.yaml',
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.presets.standalone
]
});
</script>
</body>
</html>
3. Copiar openapi.yaml a public
cp openapi.yaml public/
4. Acceder a la documentación
- OpenAPI Spec:
http://localhost:8000/openapi.yaml - Swagger UI:
http://localhost:8000/swagger-ui.html
🔧 Validación del OpenAPI
Validar sintaxis:
# Con swagger-codegen (si tienes instalado)
swagger-codegen validate -i openapi.yaml
# Online validator
# Subir a: https://validator.swagger.io/
Generar clientes:
# Generar cliente JavaScript
swagger-codegen generate -i openapi.yaml -l javascript -o client-js
# Generar cliente PHP
swagger-codegen generate -i openapi.yaml -l php -o client-php
📋 Endpoints Documentados
| Endpoint | Método | Descripción |
|---|---|---|
/health |
GET | Health check |
/info |
GET | API info |
/v1/ciudades |
GET | Ciudades (SP) |
/v1/ciudades-alt |
GET | Ciudades (QB) |
/v1/empresas |
GET | Empresas (SP) |
/v1/empresas-alt |
GET | Empresas (QB) |
/v1/empresas/{id} |
GET | Empresa por ID |
🎨 Características del OpenAPI
- ✅ OpenAPI 3.0.3 estándar
- ✅ Ejemplos completos para todas las respuestas
- ✅ Esquemas detallados para Ciudad y Empresa
- ✅ Documentación de errores con ejemplos
- ✅ Parámetros de consulta documentados
- ✅ Información de migración incluida
- ✅ Metadatos de base de datos documentados