# 📚 Configuración Swagger UI para WSCONCILIA API

## 🎯 Integración de OpenAPI/Swagger en Laravel

### 1. **Instalar L5-Swagger (Opcional)**
```bash
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
```

### 2. **Configurar Swagger UI Manual**

Crear archivo `public/swagger-ui.html`:
```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**
```bash
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:**
```bash
# Con swagger-codegen (si tienes instalado)
swagger-codegen validate -i openapi.yaml

# Online validator
# Subir a: https://validator.swagger.io/
```

### **Generar clientes:**
```bash
# 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

