# Especificación y Documentación de OpenAPI 🌐📋
El servidor web seguro de `bgustscraper` expone una especificación de API compatible con el estándar **OpenAPI 3.0.3**. Esto facilita la auto-documentación, la integración con clientes externos (SaaS, plataformas de visualización, integradores de datos) y la generación automática de clientes SDK multilingües.
La definición OpenAPI reside físicamente en: [config/openapi.json](file:///home/august/code/bgust-nlp-ecosystem/bgustscraper/config/openapi.json).
---
## 📡 1. Endpoints de la API
La API sirve los siguientes endpoints públicos y privados (securizados mediante tokens JWT):
### POST `/api/auth` (Público)
* **Objetivo:** Autenticar el acceso del cliente de administración.
* **Cuerpo de Petición (JSON):**
```json
{
"username": "admin",
"password": "change_me"
}
```
* **Respuesta Exitosa (200 OK):**
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTcxNzMwNzQ2MH0..."
}
```
* **Errores:** `401 Unauthorized` si las credenciales son incorrectas.
### GET `/api/bcv` (Protegido por JWT)
* **Objetivo:** Retornar los datos semánticos consolidados de las tasas cambiarias de Venezuela extraídos en la última tarea programada.
* **Respuesta Exitosa (200 OK):**
```json
{
"USD": 36.45,
"EUR": 39.12
}
```
* **Errores:** `401 Unauthorized` si el token expiró o no se provee la cabecera `Authorization`.
### GET `/api/cache` (Protegido por JWT)
* **Objetivo:** Obtener metadatos y estado de integridad del almacenamiento embebido y persistente `redb`.
* **Respuesta Exitosa (200 OK):**
```json
{
"database_path": "downloads/cache.db",
"status": "active",
"storage_engine": "redb",
"info": "La base de datos embebida redb está en ejecución y securizada."
}
```
### GET `/api/openapi.json` (Público)
* **Objetivo:** Servir en vivo la especificación OpenAPI estructurada del servidor para ser consumida de forma directa por herramientas de renderizado e integradores.
---
## 🛡️ 2. Esquema de Seguridad: JWT Bearer Auth
La especificación OpenAPI define un esquema de seguridad global basado en Bearer Tokens:
* **Tipo:** HTTP
* **Esquema:** Bearer
* **Formato JWT:** HS256 criptográficamente firmado y verificado por Axum en Rust.
* **Uso:** Todas las rutas bajo el prefijo `/api/bcv` y `/api/cache` requieren que el cliente incluya la cabecera HTTP:
```http
Authorization: Bearer <token_jwt>
```
---
## 🎨 3. Visualización Interactiva (Swagger / Redoc)
Para visualizar la documentación interactiva en tu navegador web de forma instantánea:
### Opción A: A través de Swagger Editor (Online)
1. Abre tu navegador en [Swagger Editor](https://editor.swagger.io/).
2. Copia el contenido del archivo `config/openapi.json`.
3. Pégalo en el editor para ver y probar interactivamente las peticiones en vivo.
### Opción B: Integración Local en Docker
El contenedor Docker de `bgustscraper` puede ser configurado en combinación con un contenedor oficial de `swagger-api/swagger-ui` para servir la interfaz interactiva en su propio puerto sin sobrecargar la API ligera de Rust.
#### Ejemplo de Configuración `docker-compose.yml`:
```yaml
version: '3.8'
services:
scraper_api:
image: bgustscraper
ports:
- "8080:8080"
environment:
- PORT=8080
- JWT_SECRET=mi_clave_secreta_aqui
swagger_ui:
image: swaggerapi/swagger-ui
ports:
- "8081:8080"
environment:
- API_URL=http://localhost:8080/api/openapi.json
```
* **Acceso:** Al levantar los servicios, abre `http://localhost:8081` para interactuar físicamente con la API a través de la UI de Swagger de manera visual y segura.