Documentação da API

Esta página aborda padrões para documentar APIs usando especificações OpenAPI em todos os serviços da Decentraland.

Objetivos

Nossa abordagem de documentação de API garante:

Padronização - Especificações OpenAPI consistentes em todos os serviços
Automação - Validação, empacotamento e implantação via GitHub Actions
Centralização - Toda a documentação de serviço publicada através do GitBook
Propriedade - A documentação vive em cada repositório de serviço
Acessibilidade - Referências de API atualizadas e amigáveis para contribuintes

Estrutura do Repositório

Cada repositório de serviço DEVE incluir um /docs diretório com a seguinte estrutura:

/docs
  openapi.yaml        # Fonte de verdade (OpenAPI 3.1)
  openapi.json        # Auto-gerado no CI para Hugo/renderers
  index.html          # Documentação autônoma auto-gerada (opcional)

Requisitos de Arquivo

`openapi.yaml`

DEVE ser o arquivo fonte canônico
DEVE usar a especificação OpenAPI 3.1
PODE ter um prefixo identificador do serviço (por exemplo, worlds-openapi.yaml)
PODE dividir em components/ ou examples/ diretórios, se necessário

`openapi.json`

Auto-gerado durante o CI/CD
Usado pelo Hugo e outros renderers
Não editar manualmente

`index.html`

Documentação autônoma auto-gerada
Construído usando Redocly
Implantado no GitHub Pages

Padrões OpenAPI

Ao escrever openapi.yaml, siga estas convenções para garantir consistência e clareza.

Resumo do Endpoint

DEVE refletir o caminho real do endpoint:

# ✅ Bom: Caminho de endpoint claro
paths:
  /world/{world_name}/about:
    get:
      summary: /world/{world_name}/about
      description: Recupera informações sobre um world específico
      
# ❌ Ruim: Resumo genérico
paths:
  /world/{world_name}/about:
    get:
      summary: Obter informações do world

Operation ID

DEVE incluir o nome do serviço para unicidade global:

# ✅ Bom: operationId com prefixo do serviço
operationId: worldsContentServer_getWorldAbout

# ✅ Bom: Outro exemplo
operationId: socialService_getFriends

# ❌ Ruim: Genérico, pode conflitar
operationId: getAbout

Convenção de nomenclatura: {serviceName}_{operationDescription}

Use camelCase
Seja descritivo, mas conciso
Inclua contexto do método HTTP quando útil (por exemplo, createUser, deleteParcel)

Versionamento

DEVE use versionamento semântico (MAJOR.MINOR.PATCH) em info.version:

openapi: 3.1.0
info:
  title: Worlds Content Server API
  version: 1.2.0  # Versionamento semântico
  description: API para gerenciar worlds da Decentraland

Regras para incremento de versão:

MAJOR: Mudanças incompatíveis (quebra de compatibilidade na API)
MINOR: Nova funcionalidade (compatível com versões anteriores)
PATCH: Correções de bugs (compatível com versões anteriores)

Tags e Agrupamento

DEVE use tags para agrupar endpoints relacionados:

tags:
  - name: Worlds
    description: Operações de gerenciamento de world
  - name: Deployments
    description: Operações de implantação de world
  - name: Health
    description: Endpoints de verificação de integridade

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

As operações são agrupadas por tag na navegação do GitBook. Agrupe endpoints relacionados sob a mesma tag para melhor organização.

Exemplo Completo

openapi: 3.1.0
info:
  title: Social Service API
  version: 2.1.0
  description: API para gerenciar interações sociais na Decentraland
  contact:
    name: Decentraland Contributors
    url: https://decentraland.org

servers:
  - url: https://social.decentraland.org
    description: Servidor de produção
  - url: https://social.decentraland.zone
    description: Servidor de staging

tags:
  - name: Friends
    description: Gerenciamento de amigos
  - name: Blocked Users
    description: Operações de bloqueio de usuários

paths:
  /friends:
    get:
      tags:
        - Friends
      summary: /friends
      operationId: socialService_getFriends
      description: Retorna uma lista dos amigos do usuário 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: Resposta bem-sucedida
          content:
            application/json:
              schema:
                type: object
                properties:
                  friends:
                    type: array
                    items:
                      $ref: '#/components/schemas/Friend'
        '401':
          description: Não autorizado

components:
  schemas:
    Friend:
      type: object
      required:
        - address
        - createdAt
      properties:
        address:
          type: string
          description: Endereço Ethereum do amigo
        createdAt:
          type: string
          format: date-time
          description: Quando a amizade foi estabelecida

Desenvolvimento Local

Visualizar Documentação Localmente

Use o Redocly CLI para visualizar sua documentação OpenAPI:

# Construir documentação HTML
yarn redocly build-docs docs/openapi.yaml -o docs/index.html

# Então abra docs/index.html no seu navegador

Adicionar ao package.json

Adicione um script de build para conveniência:

{
  "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 Especificação OpenAPI

# Validar sua especificação
redocly lint docs/openapi.yaml

# Empacotar e validar
redocly bundle docs/openapi.yaml

Configuração de Automação

Passo 1: Configurar Secrets do GitBook

Para publicar specs de API no GitBook, adicione estes secrets ao seu repositório:

Settings → Secrets and variables → Actions → New repository secret

Nome do Secret

Descrição

Onde Encontrar

GITBOOK_ORGANIZATION_ID

O ID da sua organização no GitBook

GitBook Settings → Organization

GITBOOK_TOKEN

Token da API do GitBook

GitBook Settings → API Tokens

Esses secrets DEVEM ser configurados para que o fluxo de trabalho automatizado publique no GitBook.

Passo 2: Adicionar Workflow do GitHub Actions

Criar .github/workflows/build-api-docs.yml no seu repositório:

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'  # ex.: 'social-service-api'
      node-version: '20'
    secrets: inherit

Parâmetros:

api-spec-file: Caminho para sua especificação OpenAPI (normalmente docs/openapi.yaml)
output-file: Onde gerar docs em HTML
output-directory: Diretório para os arquivos de saída
api-spec-name: Nome único para sua especificação de API (usado no GitBook)
node-version: Versão do Node.js a ser usada

Este workflow irá:

✅ Validar a especificação OpenAPI
✅ Empacotar a especificação em um único arquivo
✅ Construir documentação estática em HTML usando Redocly
✅ Implantar automaticamente no GitHub Pages
✅ Publicar a spec no GitBook (se os secrets estiverem configurados)

Passo 3: Habilitar GitHub Pages

Configure o GitHub Pages no seu repositório:

Vá para Settings → Pages
Em Build and deployment:
- Defina Source para GitHub Actions
Certifique-se de que existe um environment chamado github-pages
Salvar configurações

Após a primeira execução bem-sucedida do workflow, sua documentação estará disponível em:

Docs HTML: https://decentraland.github.io/<repo>/index.html
Spec OpenAPI: https://decentraland.github.io/<repo>/openapi.yaml
JSON Empacotado: https://decentraland.github.io/<repo>/openapi.json

Essas URLs permanecem válidas enquanto o repositório existir e o GitHub Pages estiver habilitado.

Adicionando ao GitBook

Uma vez que sua documentação de API esteja implantada, adicione-a à documentação centralizada do GitBook.

Adição Manual (Processo Atual)

Navegue até o espaço do GitBook
Vá para a Referência de API seção
Clique em Add API Reference
Insira os detalhes do seu serviço:
- Name: O nome do seu serviço (por exemplo, "Social Service")
- OpenAPI URL: https://decentraland.github.io/{repo-name}/openapi.yaml
Salvar

Recursos de Integração do GitBook

O GitBook irá automaticamente:

Analisar sua especificação OpenAPI
Gerar documentação interativa de API
Criar navegação de endpoints baseada em tags
Fornecer funcionalidade "Try it"
Manter docs sincronizados quando você atualizar a spec

Fluxo de Configuração Completo

Configuração Inicial

Atualizações Contínuas

Boas Práticas

Qualidade da Documentação

Seja descritivo: Escreva resumos e descrições claras
Forneça exemplos: Inclua exemplos de requisição/resposta
Documente erros: Descreva todas as possíveis respostas de erro
Use components: Reutilize schemas via $ref para evitar duplicação
Adicione descrições: Todo parâmetro, propriedade e resposta deve ter uma descrição

Exemplo com Melhores Práticas

paths:
  /users/{address}/friends:
    get:
      tags:
        - Friends
      summary: /users/{address}/friends
      operationId: socialService_getUserFriends
      description: |
        Recupera uma lista paginada de amigos para o usuário especificado.
        Retorna endereços de amigos e metadados incluindo quando a amizade foi estabelecida.
      parameters:
        - name: address
          in: path
          required: true
          description: Endereço Ethereum do usuário (com prefixo 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 retornar (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          description: Número de amigos a pular para paginação
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Lista de amigos recuperada com sucesso
          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 endereço inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Formato de endereço inválido'
                code: 'INVALID_ADDRESS'
        '404':
          description: Usuário não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Reutilização de Schemas

components:
  schemas:
    Error:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Mensagem de erro legível por humanos
        code:
          type: string
          description: Código de erro legível por máquina
        details:
          type: object
          description: Contexto adicional do erro
          
    PaginatedResponse:
      type: object
      required:
        - offset
        - limit
        - total
      properties:
        offset:
          type: integer
          description: Número de itens ignorados
        limit:
          type: integer
          description: Máximo de itens por página
        total:
          type: integer
          description: Número total de itens disponíveis

Schemas de Segurança

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtido do endpoint de autenticação

security:
  - BearerAuth: []

Validação e Verificações de Qualidade

Validação Pré-Commit

Adicione um hook pre-commit ou verificação no 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

Regras Comuns de Validação

Todos os paths têm operation IDs
Todas as operações têm tags
Todos os parâmetros têm descrições
Todas as respostas estão documentadas
Exemplos são fornecidos
Schemas são referenciados corretamente

Solução de Problemas

Workflow Falha

Problema: O workflow do GitHub Actions falha

Soluções:

Verifique os logs do workflow para erros de validação
Execute redocly lint docs/openapi.yaml localmente
Verifique caminhos de arquivos na configuração do workflow
Certifique-se de que os secrets estejam configurados corretamente

GitHub Pages Não Funciona

Problema: Docs não aparecem na URL do GitHub Pages

Soluções:

Verifique se o GitHub Pages está habilitado nas configurações do repositório
Verifique se o workflow foi concluído com sucesso
Aguarde alguns minutos para o GitHub Pages atualizar
Verifique se o github-pages environment existe

GitBook Não Está Sincronizando

Problema: GitBook não mostra docs de API atualizados

Soluções:

Verifique se os secrets do GitBook estão corretos
Verifique se a URL OpenAPI é acessível
Dispare manualmente uma atualização no GitBook
Verifique se a especificação OpenAPI é válida

Migração de Documentação Existente

Se você tiver documentação de API existente:

Exportar para OpenAPI: Converter docs existentes para o formato OpenAPI 3.1
Validar: Usar redocly lint para garantir conformidade
Adicionar workflow: Configurar automação do GitHub Actions
Testar: Verificar se os docs são construídos e implantados corretamente
Atualizar links: Apontar links da documentação antiga para a nova URL do GitHub Pages
Arquivar documentos antigos: Manter documentos antigos para referência durante a transição

Próximos Passos

Revisar o Well-Known Components padrões para implementação de API
Veja Padrões de Teste para diretrizes de teste de API
Confira exemplos de API existentes no Referência de API seção

Gerenciamento de Dependências - Gerenciando dependências npm e peerDependencies
Well-Known Components - WKC architecture para serviços
Padrões de Teste - Padrões de teste para serviços

Recursos

OpenAPI Specification: spec.openapis.org
Redocly CLI: redocly.com/docs/cli
Integração da API do GitBook: docs.gitbook.com
Repositório Platform Actions: github.com/decentraland/platform-actions

AnteriorVisão geral PróximoGestão de Dependências

Atualizado há 5 meses

Objetivos

Estrutura do Repositório

Requisitos de Arquivo

openapi.yaml

openapi.json

index.html

Padrões OpenAPI

Resumo do Endpoint

Operation ID

Versionamento

Tags e Agrupamento

Exemplo Completo

Desenvolvimento Local

Visualizar Documentação Localmente

Adicionar ao package.json

Instalar Redocly CLI

Validar Especificação OpenAPI

Configuração de Automação

Passo 1: Configurar Secrets do GitBook

Passo 2: Adicionar Workflow do GitHub Actions

Passo 3: Habilitar GitHub Pages

Adicionando ao GitBook

Adição Manual (Processo Atual)

Recursos de Integração do GitBook

Fluxo de Configuração Completo

Configuração Inicial

Atualizações Contínuas

Boas Práticas

Qualidade da Documentação

Exemplo com Melhores Práticas

Reutilização de Schemas

Schemas de Segurança

Validação e Verificações de Qualidade

Validação Pré-Commit

Regras Comuns de Validação

Solução de Problemas

Workflow Falha

GitHub Pages Não Funciona

GitBook Não Está Sincronizando

Migração de Documentação Existente

Próximos Passos

Related Standards

Recursos

`openapi.yaml`

`openapi.json`

`index.html`