---
title: "Integração CI/CD"
slug: "ci-cd-integration"
updated: 2026-06-15T13:19:00Z
published: 2026-06-15T13:19:00Z
canonical: "docs.document360.com/ci-cd-integration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração CI/CD

O fluxo CI/CD permite que você mantenha a documentação da API automaticamente sincronizada com seu arquivo de especificações. Em vez de enviar manualmente uma nova especificação toda vez que sua API muda, você integra a CLI do Document360 (`d360`) ao seu pipeline existente. Quando sua especificação muda, o pipeline roda e sua documentação se atualiza automaticamente.

---

## Requisitos

Antes de configurar o fluxo de CI/CD, certifique-se do seguinte:

- A versão mais recente do **Node.js** está instalada no sistema que executa o pipeline.
- Você tem sua **chave de API do Document360**, **ID de usuário** e **ID de referência da API** disponíveis.
- Seu arquivo de especificação é acessível tanto como um caminho local quanto como uma URL hospedada dentro do ambiente do pipeline.

 NOTA

Se você não está familiarizado com Node.js instalação, consulte a [documentação oficial Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) para as instruções de configuração.

### Encontrando sua chave de API, ID de usuário e ID de referência da API

O Document360 não oferece telas de busca independentes separadas para esses valores. Em vez disso, os três estão pré-preenchidos para você dentro de um comando CLI pronto para executar, disponível em dois lugares:

- **Ao criar uma nova referência:** Na janela de referência da Nova API, selecione o botão de rádio **CI/CD Flow** .
- **Para uma referência existente:** Abra a referência, clique **em Editar referência da API** e selecione **Mostrar detalhes** no banner *"Você também pode atualizar e ressincronizar a Referência da API usando nosso pacote D360 npm* ".

Qualquer uma das opções exibe o comando completo `apidocs:resync` com `--userId`, `--apiReferenceId`, e `--apiKey` já preenchido.

IMPORTANTE!

O token API encontrado em **Configurações** > **portal da base de conhecimento** > **tokens API** é para a API de Cliente (pública) do Document360 e não pode ser usado com o fluxo CI/CD d360. Sempre use o `--apiKey` valor do comando CLI pré-preenchido acima.

---

## Instalação da CLI do Document360

A ferramenta CLI Document360 é distribuída como um pacote npm chamado `d360`. Instale globalmente:

```
npm install d360 -g
```

 NOTA

Você só precisa executar esse comando de instalação uma vez. Se a CLI já estiver instalada no sistema, pule essa etapa.

---

## Configuração inicial: criação de uma nova referência de API via CLI

Se você estiver configurando CI/CD para uma nova referência de API, pode gerar a importação inicial diretamente da linha de código.

1. No portal da Base de Conhecimento, navegue até **a documentação** `{ }` da API na barra de navegação à esquerda.
2. Clique no **menu suspenso Criar** e selecione **Nova API.**
3. Na janela de referência da Nova API, selecione o botão de rádio **CI/CD Flow** .
4. Copie o comando CLI completo exibido na janela.
5. Substitua o `--path` valor no comando copiado pelo caminho para seu arquivo de especificações.

**Arquivo local:**

```
--path=/Users/yourname/projects/api/openapi.yaml
```

**URL hospedada:**

```
--path=https://example.com/api/openapi.yaml
```

1. Cole o comando atualizado no seu terminal e pressione Enter.

O Document360 faz upload do arquivo de especificação e gera a referência da API.

---

## Resincronizando uma referência de API existente

Depois que uma referência de API for criada, use o `apidocs:resync` comando para atualizá-la quando sua especificação mudar. Esse é o comando que você executará no seu pipeline de CI/CD.

```
d360 apidocs:resync \
  --apiKey=YOUR_API_KEY \
  --userId=YOUR_USER_ID \
  --apiReferenceId=YOUR_API_REFERENCE_ID \
  --path=PATH_TO_SPEC_FILE
```

Substitua os valores provisórios:

| Parâmetro | O que colocar aqui |
| --- | --- |
| `--apiKey` | Sua chave API do Document360 |
| `--userId` | Seu ID de usuário do Document360 |
| `--apiReferenceId` | O ID da referência da API para atualização |
| `--path` | Caminho completo até seu arquivo de especificações, ou uma URL apontando para ele |

 NOTA

Qualquer conteúdo personalizado que você tenha adicionado a artigos individuais de endpoints será mantido quando uma resincronização for executada. Apenas o conteúdo gerado pela especificação é atualizado.

### Gerenciando múltiplos arquivos de especificação (monorepo)

A CLI não oferece uma opção de lote — `--path` aceita um único arquivo de especificação ou URL.

Para manter múltiplos serviços sincronizados de um repositório, execute um comando separado `apidocs:resync` para cada serviço, dando a cada um seu `--apiReferenceId` próprio e `--path`.

IMPORTANTE

Sempre passe `--path` explicitamente em um mono-repo. Se for omitido, a CLI seleciona automaticamente o primeiro arquivo de especificação que encontrar, que pode não ser o que você pretende.

### Detectando falhas no seu pipeline

Atualmente, a CLI não usa seu código de saída para sinalizar se uma importação ou resincronização foi bem-sucedida. Uma resincronização falhada — por exemplo, "Resincronização falhada! Encontramos N alertas" ou um erro de API — é impresso no console, mas o processo ainda sai com código `0`. Como resultado, a etapa do pipeline parece passar mesmo quando a especificação não foi atualizada.

Para detectar falhas de forma confiável, inspecione a saída do console do comando em busca de mensagens de falha e falhe a etapa você mesmo se encontrar uma, em vez de depender do código de saída.

### Validação sem publicação

Não existe bandeira `--dry-run` . Para validar um arquivo de especificação sem fazer nenhuma alteração na sua referência de API, use o `apidocs:validate` comando:

```
d360 apidocs:validate --apiKey=YOUR_API_KEY --path=PATH_TO_SPEC_FILE
```

Ele reporta quaisquer erros ou avisos na especificação sem publicar ou atualizar a referência. Note que `apidocs:validate` toma apenas `--apiKey` e `--path` — não requer `--userId` ou `--apiReferenceId`. Rodar como um passo antes `apidocs:resync` é uma boa forma de detectar problemas de especificação cedo em um pipeline.

---

## Gerenciando sua chave API no CI

Sua chave API é uma credencial secreta. Não codifique isso diretamente nos arquivos de configuração do seu pipeline nem faça commit no controle de versão.

Armazene-a como variável de ambiente ou segredo na sua plataforma CI e faça referência no comando:

```
d360 apidocs:resync \
  --apiKey=$DOCUMENT360_API_KEY \
  --userId=$DOCUMENT360_USER_ID \
  --apiReferenceId=$API_REFERENCE_ID \
  --path=./openapi.yaml
```

IMPORTANTE!

Se você regenerar sua chave API no portal Document360, a chave antiga imediatamente se torna inválida. Atualize o segredo na sua plataforma CI antes da próxima execução do pipeline, ou seu resync falhará.

---

## Exemplos de oleodutos

### Ações no GitHub

Crie `.github/workflows/api-docs.yml`:

```
name: Sync API docs to Document360
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
jobs:
  resync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
      - run: npm install d360 -g
      - name: Resync to Document360
        shell: bash
        run: |
          set +e
          d360 apidocs:resync \
            --apiKey="${{ secrets.DOCUMENT360_API_KEY }}" \
            --userId="${{ secrets.DOCUMENT360_USER_ID }}" \
            --apiReferenceId="${{ secrets.API_REFERENCE_ID }}" \
            --path=./openapi.yaml \
            --force 2>&1 | tee resync.out
          grep -qi "Resync Successful" resync.out \
            || { echo "::error::Document360 resync failed"; exit 1; }
```

Armazene `DOCUMENT360_API_KEY`, `DOCUMENT360_USER_ID`, e `API_REFERENCE_ID` como segredos do repositório, usando os valores do comando CLI pré-preenchido.

### GitLab CI

Adicione o seguinte a `.gitlab-ci.yml`:

```
stages:
  - sync

sync-api-docs:
  stage: sync
  image: node:lts
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      changes: [openapi.yaml]
  script:
    - npm install d360 -g
    - |
      set +e
      d360 apidocs:resync \
        --apiKey="$DOCUMENT360_API_KEY" \
        --userId="$DOCUMENT360_USER_ID" \
        --apiReferenceId="$API_REFERENCE_ID" \
        --path=./openapi.yaml \
        --force 2>&1 | tee resync.out
      grep -qi "Resync Successful" resync.out || { echo "Document360 resync failed"; exit 1; }
```

Armazene `DOCUMENT360_API_KEY`, `DOCUMENT360_USER_ID`, e `API_REFERENCE_ID` como variáveis CI/CD mascaradas em **Configurações** > **CI/** CD **> Variáveis**.

 NOTA

O GitLab não pode mascarar valores contendo hífens, então o ID do usuário e o ID de referência da API serão armazenados sem mascaramento.

---

## Suporte a Webhook em CI/CD

Webhooks definidos na sua especificação OpenAPI 3.1 são totalmente suportados em operações de resincronização CI/CD. Quando uma resincronização é executada, as definições do webhook são atualizadas junto com o restante do conteúdo da especificação.

---

## Links úteis

- [Pacote D360 NPM](https://www.npmjs.com/package/d360)
- [Código-fonte do d360](https://github.com/document360/d360)