Nexus - AI Task Orchestrator

05-api-documentation-sync
Procedimiento: Sincronizaci├│n de Documentaci├│n API

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
7782 caracteres
# Procedimiento: Sincronizaci├│n de Documentaci├│n API

## Metadata
- **ID**: PROC-05
- **Frecuencia**: Post-deploy o Semanal
- **Duraci├│n estimada**: 15-30 min
- **Requiere**: Acceso al repositorio, API en ejecuci├│n (opcional)
- **Dependencias**: PROC-21 (post-deploy trigger)
- **Bloquea**: Ninguno
- **Agentes**: documentation-engineer, dotnet-architect

---

## Objetivo

Mantener sincronizada la documentaci├│n de API:
1. Regenerar especificaci├│n OpenAPI/Swagger
2. Verificar que endpoints documentados coinciden con c├│digo
3. Actualizar ejemplos de request/response
4. Validar que breaking changes est├ín documentados

---

## Detecci├│n de Stack

### .NET (ASP.NET Core)

```bash
# Detectar si usa Swagger/OpenAPI
grep -r "Swashbuckle\|NSwag\|OpenApi" *.csproj

# Buscar configuraci├│n
grep -r "AddSwaggerGen\|UseSwagger\|AddOpenApi" src --include="*.cs"
```

### Node.js

```bash
# Detectar si usa documentaci├│n API
grep -E "swagger|openapi|@api" package.json
```

---

## Checklist Ejecutable

### 1. Identificar Tipo de Documentaci├│n API

- [ ] Swagger/Swashbuckle (.NET)
- [ ] NSwag (.NET)
- [ ] OpenAPI manual (openapi.json/yaml)
- [ ] Postman Collection
- [ ] Otro: ___

### 2. Regenerar Especificaci├│n OpenAPI

#### Para .NET con Swagger

```bash
# Opci├│n 1: Ejecutar la API y obtener spec
dotnet run &
sleep 10
curl http://localhost:5000/swagger/v1/swagger.json -o docs/api/openapi.json
kill %1

# Opci├│n 2: Usar herramienta CLI (si est├í instalada)
dotnet swagger tofile --output docs/api/openapi.json ./bin/Debug/net9.0/Api.dll v1
```

#### Para .NET con NSwag

```bash
# Usando NSwag CLI
nswag run nswag.json
```

- [ ] Especificaci├│n OpenAPI regenerada
- [ ] Archivo guardado en docs/api/

### 3. Comparar Endpoints C├│digo vs Documentaci├│n

```bash
# Extraer endpoints del c├│digo (.NET)
grep -rE "\[(Http(Get|Post|Put|Delete|Patch))\]|\[Route\(" src --include="*.cs" | \
  grep -oE '"[^"]*"' | sort -u

# Extraer endpoints del OpenAPI
cat docs/api/openapi.json | jq '.paths | keys[]' | sort -u

# Comparar
diff <(endpoints_codigo) <(endpoints_openapi)
```

- [ ] Todos los endpoints del c├│digo est├ín documentados
- [ ] No hay endpoints fantasma en documentaci├│n

### 4. Validar Esquemas de Request/Response

```bash
# Extraer modelos del c├│digo
grep -rE "public class.*Request|public class.*Response|public record" src --include="*.cs" | \
  grep -oE "class \w+|record \w+" | sort -u

# Comparar con schemas en OpenAPI
cat docs/api/openapi.json | jq '.components.schemas | keys[]' | sort -u
```

- [ ] Modelos de request documentados
- [ ] Modelos de response documentados
- [ ] Tipos de datos correctos

### 5. Verificar Ejemplos

```bash
# Buscar ejemplos en OpenAPI
cat docs/api/openapi.json | jq '.paths | .. | .example? // empty' | head -20

# Verificar que ejemplos son v├ílidos JSON
# (validar estructura contra schema)
```

- [ ] Endpoints tienen ejemplos
- [ ] Ejemplos son v├ílidos
- [ ] Ejemplos reflejan casos de uso reales

### 6. Detectar Breaking Changes

```bash
# Comparar con versi├│n anterior
git diff HEAD~10 -- docs/api/openapi.json | grep -E "^\+|^\-" | head -50

# Cambios que son breaking:
# - Endpoints eliminados
# - Campos obligatorios a├▒adidos
# - Tipos de datos cambiados
# - C├│digos de respuesta cambiados
```

**Breaking changes a documentar:**
- [ ] Endpoints eliminados
- [ ] Campos requeridos nuevos
- [ ] Cambios de tipo de datos
- [ ] Cambios en c├│digos de respuesta

### 7. Actualizar Documentaci├│n Adicional

```bash
# Verificar si hay docs manuales que actualizar
ls docs/*.md docs/api/*.md 2>/dev/null

# Archivos t├¡picos:
# - docs/api/README.md
# - docs/api/authentication.md
# - docs/api/errors.md
# - docs/api/changelog.md
```

- [ ] README de API actualizado
- [ ] Ejemplos de autenticaci├│n correctos
- [ ] C├│digos de error documentados
- [ ] Changelog actualizado (si hay breaking changes)

### 8. Validar Especificaci├│n OpenAPI

```bash
# Usar herramienta de validaci├│n
npx @apidevtools/swagger-cli validate docs/api/openapi.json

# O con spectral
npx @stoplight/spectral lint docs/api/openapi.json
```

- [ ] Especificaci├│n v├ílida seg├║n est├índar OpenAPI
- [ ] Sin warnings cr├¡ticos

---

## Para Postman Collections

### Actualizar Collection

```bash
# Exportar desde Postman CLI (si est├í configurado)
postman collection export --collection "API Collection" --output docs/api/collection.json

# O sincronizar con OpenAPI
# Importar openapi.json en Postman y exportar collection
```

- [ ] Collection exportada
- [ ] Variables de entorno actualizadas
- [ ] Ejemplos funcionando

---

## Output Esperado

```
====== PROC-05 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]
Tipo de documentaci├│n: Swagger/OpenAPI

ESPECIFICACI├ôN:
- Archivo: docs/api/openapi.json
- Versi├│n: X.X.X
- ├Ültima generaci├│n: [timestamp]

ENDPOINTS:
- En c├│digo: X
- En documentaci├│n: Y
- Sincronizados: Ô£à / ÔØî Faltan: [lista]

MODELOS:
- Request models: X
- Response models: Y
- Documentados: Z

BREAKING CHANGES DETECTADOS:
- [lista o "Ninguno"]

VALIDACI├ôN:
- OpenAPI v├ílido: Ô£à / ÔØî
- Errores: [lista si hay]

ARCHIVOS ACTUALIZADOS:
- docs/api/openapi.json Ô£à
- docs/api/README.md ÔÜá´©Å Revisar
- docs/api/changelog.md ÔÜá´©Å Actualizar

ACCIONES PENDIENTES:
1. [acci├│n si hay]
```

---

## Criterios de ├ëxito

- [ ] OpenAPI regenerado y v├ílido
- [ ] 100% endpoints documentados
- [ ] Breaking changes documentados
- [ ] Ejemplos actualizados

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| CRITICAL | Breaking change sin documentar | Bloquear release |
| WARNING | Endpoints sin documentar | Crear tarea Holded |
| WARNING | OpenAPI inv├ílido | Corregir inmediatamente |
| INFO | Todo sincronizado | Documentar estado |

---

## Automatizaci├│n

En ejecuci├│n no-interactiva (post-deploy):
1. Regenerar OpenAPI desde c├│digo
2. Validar especificaci├│n
3. Comparar con versi├│n anterior
4. Detectar breaking changes
5. Actualizar archivos
6. Commit autom├ítico si hay cambios

---


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-05 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "score": 85, "drift_percent": 8,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-05"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- endpoints_documented, missing_docs, sync_percent

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Ejecuciones

| Fecha | Proyecto | Endpoints | Breaking Changes | Validaci├│n | Acciones |
|-------|----------|-----------|------------------|------------|----------|
| | | | | | |