Documentación de API

Esta página cubre los estándares para documentar APIs usando especificaciones OpenAPI en todos los servicios de Decentraland.

Objetivos

Nuestro enfoque de documentación de API garantiza:

• Estandarización - Especificaciones OpenAPI consistentes en todos los servicios

• Automatización - Validación, empaquetado y despliegue mediante GitHub Actions

• Centralización - Toda la documentación de servicios publicada a través de GitBook

• Propiedad - La documentación vive en el repositorio de cada servicio

• Accesibilidad - Referencias de API amigables para contribuidores y actualizadas

---

Estructura del repositorio

Cada repositorio de servicio DEBE incluir un /docs directorio con la siguiente estructura:

/docs
  openapi.yaml        # Fuente de verdad (OpenAPI 3.1)
  openapi.json        # Generado automáticamente en CI para Hugo/renderers
  index.html          # Documentación independiente generada automáticamente (opcional)

Requisitos de archivos

openapi.yaml

• DEBE ser el archivo fuente canónico

• DEBE usar la especificación OpenAPI 3.1

• PUEDE tener un prefijo que identifique el servicio (p. ej., worlds-openapi.yaml)

• PUEDE dividirse en components/ o examples/ directorios si es necesario

openapi.json

• Generado automáticamente durante CI/CD

• Usado por Hugo y otros renderers

• No editar manualmente

index.html

• Documentación independiente generada automáticamente

• Construido usando Redocly

• Desplegado en GitHub Pages

---

Estándares OpenAPI

Al escribir openapi.yaml, sigue estas convenciones para asegurar consistencia y claridad.

Resumen del endpoint

DEBE refleja la ruta real del endpoint:

# ✅ Bueno: Ruta de endpoint clara
paths:
  /world/{world_name}/about:
    get:
      summary: /world/{world_name}/about
      description: Recupera información sobre un world específico
      
# ❌ Malo: Resumen genérico
paths:
  /world/{world_name}/about:
    get:
      summary: Obtener info del world

Operation ID

DEBE incluye el nombre del servicio para unicidad global:

# ✅ Bueno: Operation ID con prefijo de servicio
operationId: worldsContentServer_getWorldAbout

# ✅ Bueno: Otro ejemplo
operationId: socialService_getFriends

# ❌ Malo: Genérico, podría entrar en conflicto
operationId: getAbout

Convención de nombres: {serviceName}_{operationDescription}

• Usa camelCase

• Sé descriptivo pero conciso

• Incluye el contexto del método HTTP cuando sea útil (p. ej., createUser, deleteParcel)

Versionado

DEBE usa versionado semántico (MAJOR.MINOR.PATCH) en info.version:

openapi: 3.1.0
info:
  title: Worlds Content Server API
  version: 1.2.0  # Versionado semántico
  description: API para gestionar Decentraland worlds

Reglas para incrementar la versión:

• MAJOR: Cambios incompatibles (cambios rompientes en la API)

• MINOR: Nueva funcionalidad (compatible hacia atrás)

• PATCH: Correcciones de bugs (compatible hacia atrás)

Etiquetas y agrupación

DEBE usa tags para agrupar endpoints relacionados:

tags:
  - name: Worlds
    description: Operaciones de gestión de worlds
  - name: Deployments
    description: Operaciones de despliegue de worlds
  - name: Health
    description: Endpoints de chequeo de salud

paths:
  /worlds:
    get:
      tags:
        - Worlds
      summary: /worlds
      operationId: worldsContentServer_listWorlds
      
  /worlds/{world_name}/about:
    get:
      tags:
        - Worlds
      summary: /worlds/{world_name}/about
      operationId: worldsContentServer_getWorldAbout

Las operaciones se agrupan por tag en la navegación de GitBook. Agrupa endpoints relacionados bajo el mismo tag para una mejor organización.

Ejemplo completo

openapi: 3.1.0
info:
  title: Social Service API
  version: 2.1.0
  description: API para gestionar interacciones sociales en Decentraland
  contact:
    name: Decentraland Contributors
    url: https://decentraland.org

servers:
  - url: https://social.decentraland.org
    description: Servidor de producción
  - url: https://social.decentraland.zone
    description: Servidor de staging

tags:
  - name: Friends
    description: Gestión de amigos
  - name: Blocked Users
    description: Operaciones de bloqueo de usuarios

paths:
  /friends:
    get:
      tags:
        - Friends
      summary: /friends
      operationId: socialService_getFriends
      description: Devuelve la lista de amigos del usuario autenticado
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Respuesta exitosa
          content:
            application/json:
              schema:
                type: object
                properties:
                  friends:
                    type: array
                    items:
                      $ref: '#/components/schemas/Friend'
        '401':
          description: No autorizado

components:
  schemas:
    Friend:
      type: object
      required:
        - address
        - createdAt
      properties:
        address:
          type: string
          description: Dirección de Ethereum del amigo
        createdAt:
          type: string
          format: date-time
          description: Cuando se estableció la amistad

---

Desarrollo local

Previsualizar documentación localmente

Usa Redocly CLI para previsualizar tu documentación OpenAPI:

# Construir documentación HTML
yarn redocly build-docs docs/openapi.yaml -o docs/index.html

# Luego abre docs/index.html en tu navegador

Agregar a package.json

Agrega un script de build por conveniencia:

{
  "scripts": {
    "build:api": "redocly bundle docs/openapi.yaml -o docs/openapi.json --ext json && redocly build-docs docs/openapi.yaml -o docs/index.html",
    "preview:api": "redocly preview-docs docs/openapi.yaml"
  }
}

Instalar Redocly CLI

# Usando npm
npm install -g @redocly/cli

# Usando yarn
yarn global add @redocly/cli

Validar especificación OpenAPI

# Valida tu especificación
redocly lint docs/openapi.yaml

# Empaquetar y validar
redocly bundle docs/openapi.yaml

---

Configuración de automatización

Paso 1: Configurar secretos de GitBook

Para publicar especificaciones de API en GitBook, agrega estos secretos a tu repositorio:

Settings → Secrets and variables → Actions → New repository secret

Nombre del secreto	Descripción	Dónde encontrar
GITBOOK_ORGANIZATION_ID	El ID de tu organización en GitBook	GitBook Settings → Organization
GITBOOK_TOKEN	Token de la API de GitBook	GitBook Settings → API Tokens

Estos secretos DEBEN estar configurados para que el flujo de trabajo automatizado publique en GitBook.

Paso 2: Agregar workflow de GitHub Actions

Crear .github/workflows/build-api-docs.yml en tu repositorio:

name: build-app-docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
  pull_request:
    paths:
      - 'docs/**'

jobs:
  build:
    uses: decentraland/platform-actions/.github/workflows/apps-docs.yml@main
    with:
      api-spec-file: 'docs/openapi.yaml'
      output-file: 'docs/index.html'
      output-directory: './docs'
      api-spec-name: '{service-name}-api'  # p. ej., 'social-service-api'
      node-version: '20'
    secrets: inherit

Parámetros:

• api-spec-file: Ruta a tu especificación OpenAPI (usualmente docs/openapi.yaml)

• output-file: Dónde generar la documentación HTML

• output-directory: Directorio para los archivos de salida

• api-spec-name: Nombre único para tu especificación de API (usado en GitBook)

• node-version: Versión de Node.js a usar

Este workflow hará:

1. ✅ Validar la especificación OpenAPI

2. ✅ Empaquetar la especificación en un único archivo

3. ✅ Construir documentación HTML estática usando Redocly

4. ✅ Desplegar automáticamente en GitHub Pages

5. ✅ Publicar la especificación en GitBook (si los secretos están configurados)

Paso 3: Habilitar GitHub Pages

Configura GitHub Pages en tu repositorio:

1. Ve a Settings → Pages

2. Bajo Build and deployment:

   • Establece Source a GitHub Actions

3. Asegúrate de que exista un environment llamado github-pages

4. Guardar configuraciones

Después de la primera ejecución exitosa del workflow, tu documentación estará disponible en:

• Docs HTML: https://decentraland.github.io/<repo>/index.html

• Especificación OpenAPI: https://decentraland.github.io/<repo>/openapi.yaml

• JSON empaquetado: https://decentraland.github.io/<repo>/openapi.json

Estas URLs permanecen válidas mientras el repositorio exista y GitHub Pages esté habilitado.

---

Agregar a GitBook

Una vez que tu documentación de API esté desplegada, agrégala a la documentación centralizada en GitBook.

Adición manual (proceso actual)

1. Navega al espacio de GitBook

2. Ve a la API Reference sección

3. Haz clic en Add API Reference

4. Introduce los detalles de tu servicio:

   • Name: El nombre de tu servicio (p. ej., "Social Service")

   • OpenAPI URL: https://decentraland.github.io/{repo-name}/openapi.yaml

5. Guardar

Funciones de integración de GitBook

GitBook hará automáticamente:

• Parsear tu especificación OpenAPI

• Generar documentación interactiva de la API

• Crear navegación de endpoints basada en tags

• Proveer funcionalidad de "Try it"

• Mantener la documentación sincronizada cuando actualices la especificación

---

Flujo de configuración completo

Configuración inicial

Actualizaciones continuas

---

Buenas prácticas

Calidad de la documentación

• Sé descriptivo: Escribe resúmenes y descripciones claras

• Proporciona ejemplos: Incluye ejemplos de request/response

• Documenta errores: Describe todas las posibles respuestas de error

• Usa components: Reutiliza esquemas vía $ref para evitar duplicación

• Agrega descripciones: Cada parámetro, propiedad y respuesta debe tener una descripción

Ejemplo con buenas prácticas

paths:
  /users/{address}/friends:
    get:
      tags:
        - Friends
      summary: /users/{address}/friends
      operationId: socialService_getUserFriends
      description: |
        Recupera una lista paginada de amigos para el usuario especificado.
        Devuelve direcciones de amigos y metadatos incluyendo cuándo se estableció la amistad.
      parameters:
        - name: address
          in: path
          required: true
          description: Dirección de Ethereum del usuario (con prefijo 0x)
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
          example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: limit
          in: query
          description: Número máximo de amigos a devolver (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          description: Número de amigos a omitir para paginación
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Lista de amigos recuperada con éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendsResponse'
              example:
                friends:
                  - address: '0xabcdef...'
                    createdAt: '2024-01-15T10:30:00Z'
                total: 42
                offset: 0
                limit: 50
        '400':
          description: Formato de dirección inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Formato de dirección inválido'
                code: 'INVALID_ADDRESS'
        '404':
          description: Usuario no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Reutilización de esquemas

components:
  schemas:
    Error:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Mensaje de error legible por humanos
        code:
          type: string
          description: Código de error legible por máquina
        details:
          type: object
          description: Contexto adicional del error
          
    PaginatedResponse:
      type: object
      required:
        - offset
        - limit
        - total
      properties:
        offset:
          type: integer
          description: Número de elementos omitidos
        limit:
          type: integer
          description: Máximo de elementos por página
        total:
          type: integer
          description: Número total de elementos disponibles

Esquemas de seguridad

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtenido desde el endpoint de autenticación

security:
  - BearerAuth: []

---

Validaciones y controles de calidad

Validación pre-commit

Agrega un hook pre-commit o una comprobación en CI:

# .github/workflows/validate-api-spec.yml
name: Validate API Spec

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install -g @redocly/cli
      - run: redocly lint docs/openapi.yaml

Reglas comunes de validación

• Todas las paths tienen operation IDs

• Todas las operaciones tienen tags

• Todos los parámetros tienen descripciones

• Todas las respuestas están documentadas

• Se proporcionan ejemplos

• Los esquemas están referenciados correctamente

---

Solución de problemas

El workflow falla

Problema: El workflow de GitHub Actions falla

Soluciones:

• Revisa los logs del workflow por errores de validación

• Ejecuta redocly lint docs/openapi.yaml localmente

• Verifica las rutas de archivos en la configuración del workflow

• Asegúrate de que los secretos estén configurados correctamente

GitHub Pages no funciona

Problema: Los docs no aparecen en la URL de GitHub Pages

Soluciones:

• Verifica que GitHub Pages esté habilitado en la configuración del repositorio

• Comprueba que el workflow se haya completado exitosamente

• Espera unos minutos para que GitHub Pages se actualice

• Verifica que el github-pages environment exista

GitBook no se sincroniza

Problema: GitBook no muestra la documentación de API actualizada

Soluciones:

• Verifica que los secretos de GitBook sean correctos

• Comprueba que la URL OpenAPI sea accesible

• Forzar una actualización manual en GitBook

• Verifica que la especificación OpenAPI sea válida

---

Migración desde documentación existente

Si tienes documentación de API existente:

1. Exportar a OpenAPI: Convertir la documentación existente al formato OpenAPI 3.1

2. Validar: Usar redocly lint para asegurar el cumplimiento

3. Agregar workflow: Configurar la automatización con GitHub Actions

4. Probar: Verificar que la documentación se compile y despliegue correctamente

5. Actualizar enlaces: Apuntar los enlaces de la documentación antigua a la nueva URL de GitHub Pages

6. Archivar la documentación antigua: Mantener la documentación antigua como referencia durante la transición

---

Próximos pasos

• Revisar el Well-Known Components estándares para la implementación de la API

• Ver Testing Standards para las pautas de pruebas de la API

• Consulta ejemplos de API existentes en el API Reference sección

Related Standards

• Gestión de dependencias - Gestión de dependencias npm y peerDependencies

• Well-Known Components - Arquitectura WKC para servicios

• Testing Standards - Patrones de pruebas para servicios

Recursos

• OpenAPI Specification: spec.openapis.org

• Redocly CLI: redocly.com/docs/cli

• Integración de API de GitBook: docs.gitbook.com

• Repositorio de Platform Actions: github.com/decentraland/platform-actions