89 lines
2.3 KiB
Markdown
89 lines
2.3 KiB
Markdown
# 📚 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
|
|
|