> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-pt/guias-para-colaboradores/api-documentation.md).

# Documentação da API

Esta página aborda os 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 dos serviços publicada por meio do GitBook
* **Propriedade** - A documentação fica em cada repositório do serviço
* **Acessibilidade** - Referências de API fáceis de usar por contribuidores e atualizadas

***

## Estrutura do repositório

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

```bash
/docs
  openapi.yaml        # Fonte da verdade (OpenAPI 3.1)
  openapi.json        # Gerado automaticamente no CI para Hugo/renderers
  index.html          # Documentação independente gerada automaticamente (opcional)
```

### Requisitos dos arquivos

#### `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** dividido em `components/` ou `examples/` diretórios, se necessário

#### `openapi.json`

* Gerado automaticamente durante CI/CD
* Usado por Hugo e outros renderers
* Não editar manualmente

#### `index.html`

* Documentação independente gerada automaticamente
* Criada com Redocly
* Implantada 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:

```yaml
# ✅ 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
```

### ID da operação

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

```yaml
# ✅ Bom: ID da operação 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}`

* Usar camelCase
* Ser descritivo, mas conciso
* Incluir o contexto do método HTTP quando útil (por exemplo, `createUser`, `deleteParcel`)

### Versionamento

**DEVE** usar versionamento semântico (`MAJOR.MINOR.PATCH`) em `info.version`:

```yaml
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 de incremento de versão**:

* **MAJOR**: Alterações incompatíveis (quebram a compatibilidade)
* **MINOR**: Nova funcionalidade (compatível com versões anteriores)
* **PATCH**: Correções de bugs (compatível com versões anteriores)

### Tags e agrupamento

**DEVE** usar tags para agrupar endpoints relacionados:

```yaml
tags:
  - name: Worlds
    description: Operações de gerenciamento de Worlds
  - name: Deployments
    description: Operações de implantação de Worlds
  - name: Health
    description: Endpoints de verificação de saúde

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
```

{% hint style="info" %}
As operações são agrupadas por tag na navegação do GitBook. Agrupe endpoints relacionados na mesma tag para uma melhor organização.
{% endhint %}

### Exemplo completo

```yaml
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

### Pré-visualizar a documentação localmente

Use a Redocly CLI para pré-visualizar sua documentação OpenAPI:

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

# Em seguida, abra docs/index.html no seu navegador
```

### Adicionar ao package.json

Adicione um script de build por conveniência:

```json
{
  "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 a Redocly CLI

```bash
# Usando npm
npm install -g @redocly/cli

# Usando yarn
yarn global add @redocly/cli
```

### Validar a especificação OpenAPI

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

# Empacotar e validar
redocly bundle docs/openapi.yaml
```

***

## Configuração da automação

### Etapa 1: Configurar os segredos do GitBook

Para publicar especificações de API no GitBook, adicione estes segredos ao seu repositório:

**Configurações → Secrets and variables → Actions → Novo segredo do repositório**

| Nome do segredo           | Descrição                        | Onde encontrar                  |
| ------------------------- | -------------------------------- | ------------------------------- |
| `GITBOOK_ORGANIZATION_ID` | Seu ID da organização do GitBook | GitBook Settings → Organization |
| `GITBOOK_TOKEN`           | Token da API do GitBook          | GitBook Settings → API Tokens   |

{% hint style="warning" %}
Estes segredos DEVEM ser configurados para que o fluxo de trabalho automatizado publique no GitBook.
{% endhint %}

### Etapa 2: Adicionar o workflow do GitHub Actions

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

```yaml
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'  # por exemplo, 'social-service-api'
      node-version: '20'
    secrets: inherit
```

**Parâmetros**:

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

**Este workflow irá**:

1. ✅ Validar a especificação OpenAPI
2. ✅ Empacotar a especificação em um único arquivo
3. ✅ Gerar documentação HTML estática usando Redocly
4. ✅ Implantar automaticamente no GitHub Pages
5. ✅ Publicar a especificação no GitBook (se os segredos estiverem configurados)

### Etapa 3: Ativar o GitHub Pages

Configure o GitHub Pages no seu repositório:

1. Acesse **Settings → Pages**
2. Em **Build and deployment**:
   * Defina **Source** para **GitHub Actions**
3. Certifique-se de que haja um ambiente chamado **github-pages**
4. Salvar configurações

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

* **Documentação HTML**: `https://decentraland.github.io/<repo>/index.html`
* **Especificação OpenAPI**: `https://decentraland.github.io/<repo>/openapi.yaml`
* **JSON empacotado**: `https://decentraland.github.io/<repo>/openapi.json`

{% hint style="success" %}
Essas URLs permanecem válidas enquanto o repositório existir e o GitHub Pages estiver ativado.
{% endhint %}

***

## Adicionando ao GitBook

Depois que sua documentação de API for implantada, adicione-a à documentação centralizada do GitBook.

### Adição manual (processo atual)

1. Navegue até o espaço do GitBook
2. Vá para a **Referência da API** seção
3. Clique em **Adicionar referência de API**
4. Insira os detalhes do seu serviço:
   * **Nome**: Nome do seu serviço (por exemplo, "Social Service")
   * **URL da OpenAPI**: `https://decentraland.github.io/{repo-name}/openapi.yaml`
5. 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 com base em tags
* Fornecer a funcionalidade "Try it"
* Manter a documentação sincronizada quando você atualizar a especificação

***

## Fluxo completo de configuração

### Configuração inicial

```mermaid
graph TD
    A[Criar /docs/openapi.yaml] --> B[Adicionar o workflow do GitHub Actions]
    B --> C[Configurar os segredos do GitBook]
    C --> D[Ativar o GitHub Pages]
    D --> E[Fazer push para a branch main]
    E --> F[O workflow é executado automaticamente]
    F --> G[Docs implantados no GitHub Pages]
    G --> H[Adicionar ao GitBook manualmente]
```

### Atualizações contínuas

```mermaid
graph LR
    A[Atualizar openapi.yaml] --> B[Criar PR]
    B --> C[O workflow valida]
    C --> D[Mesclar na main]
    D --> E[Implantação automática no GitHub Pages]
    E --> F[GitBook sincroniza automaticamente]
```

***

## Melhores práticas

### Qualidade da documentação

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

### Exemplo com boas práticas

```yaml
paths:
  /users/{address}/friends:
    get:
      tags:
        - Friends
      resumo: /users/{address}/friends
      operationId: socialService_getUserFriends
      description: |
        Recupera uma lista paginada de amigos para o usuário especificado.
        Retorna os endereços dos 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 ignorar 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

```yaml
components:
  schemas:
    Erro:
      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: Número máximo de itens por página
        total:
          type: integer
          description: Número total de itens disponíveis
```

### Schemas de Segurança

```yaml
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 pré-commit ou uma verificação de CI:

```yaml
# .github/workflows/validate-api-spec.yml
name: Validar Especificação da API

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 caminhos têm IDs de operação
* 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
* Os Schemas são referenciados corretamente

***

## Solução de Problemas

### Falha do Fluxo de Trabalho

**Problema**: o fluxo de trabalho do GitHub Actions falha

**Soluções**:

* Verifique os logs do fluxo de trabalho para erros de validação
* Executar `redocly lint docs/openapi.yaml` localmente
* Verifique os caminhos dos arquivos na configuração do fluxo de trabalho
* Garanta que os secrets estejam configurados corretamente

### GitHub Pages Não Está Funcionando

**Problema**: a documentação não aparece na URL do GitHub Pages

**Soluções**:

* Verifique se o GitHub Pages está ativado nas configurações do repositório
* Verifique se o fluxo de trabalho foi concluído com sucesso
* Aguarde alguns minutos para o GitHub Pages atualizar
* Verifique o `github-pages` ambiente existe

### GitBook Não Está Sincronizando

**Problema**: o GitBook não está mostrando a documentação da API atualizada

**Soluções**:

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

***

## Migração da Documentação Existente

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

1. **Exportar para OpenAPI**: Converta a documentação existente para o formato OpenAPI 3.1
2. **Validar**: Use `redocly lint` para garantir conformidade
3. **Adicionar fluxo de trabalho**: Configure a automação do GitHub Actions
4. **Testar**: Verifique se a documentação é compilada e implantada corretamente
5. **Atualizar links**: Aponte os links da documentação antiga para a nova URL do GitHub Pages
6. **Arquivar docs antigas**: Mantenha as docs antigas como referência durante a transição

***

## Próximos passos

* Revise os [Componentes Bem Conhecidos](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/well-known-components/README.md) padrões para implementação da API
* Veja [Padrões de Teste](/contributor/contributor-pt/guias-para-colaboradores/testing-standards.md) para diretrizes de teste da API
* Confira exemplos de API existentes em [Referência da API](https://docs.decentraland.org) seção

## Padrões Relacionados

* [Gerenciamento de Dependências](/contributor/contributor-pt/guias-para-colaboradores/dependency-management.md) - Gerenciando dependências npm e peerDependencies
* [Componentes Bem Conhecidos](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/well-known-components/README.md) - arquitetura WKC para serviços
* [Padrões de Teste](/contributor/contributor-pt/guias-para-colaboradores/testing-standards.md) - padrões de teste para serviços

## Recursos

* **Especificação OpenAPI**: [spec.openapis.org](https://spec.openapis.org/oas/latest.html)
* **Redocly CLI**: [redocly.com/docs/cli](https://redocly.com/docs/cli/)
* **Integração da API do GitBook**: [docs.gitbook.com](https://docs.gitbook.com)
* **Repositório Platform Actions**: [github.com/decentraland/platform-actions](https://github.com/decentraland/platform-actions)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/contributor/contributor-pt/guias-para-colaboradores/api-documentation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.