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.

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.

Instalação da CLI do Document360

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

npm install d360 -g

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

6. 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:

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.

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

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.

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
• Código-fonte do d360