elvoro-apidex

CLI oficial de governança da plataforma Apidex para pipelines CI/CD.

Use o apidex para:

• OpenAPI — validar, comparar (diff) e publicar specs no catálogo de APIs
• Microserviços — validar, comparar e publicar manifests no catálogo de microserviços
• MCP — validar, comparar e publicar manifests no catálogo MCP

Público-alvo: times de desenvolvimento e plataforma que querem governança de contratos de API, inventário de microserviços e registry MCP direto no pipeline — sem sair do GitHub Actions, GitLab CI ou Jenkins.

Requisitos

• Node.js 18+
• Service API key apk_* criada no app Apidex (obrigatória para diff e publish; opcional em validate com --local-only)

Instalação

Instalação global (recomendada em runners de CI):

npm install -g elvoro-apidex

Execução pontual, sem instalar:

npx elvoro-apidex --help

Após instalar, o binário disponível é apidex:

apidex --version
# 0.1.0

Autenticação

1. Criar a API key no Apidex

1. Acesse https://apidex.com.br e faça login.
2. Vá em Configurações → Organização → API Keys.
3. Crie uma nova key com as permissões necessárias:
   • validate:read — para validate e diff
   • publish:read / publish:write — para publish
4. Para publicar em produção (--env prod), a key precisa ter allowProd: true.

2. Formato da key

Todas as service API keys usam o prefixo apk_* seguido de um identificador de lookup e o segredo (ex.: apk_a1b2c3d4_...).

Chaves legadas com prefixo apk_test_* ou apk_live_* continuam válidas.

Para publicar em produção (--env prod), a key precisa ter allowProd: true — independentemente do prefixo.

3. Como passar a key para o CLI

Variável de ambiente (recomendado em CI):

export APIDEX_API_KEY="apk_a1b2c3d4_xxxxxxxx"

Flag na linha de comando:

apidex validate ./openapi.yaml --api-key "apk_a1b2c3d4_xxxxxxxx" --api <uuid>

Segurança: nunca commite a API key no repositório. Use secrets do CI (APIDEX_API_KEY no GitHub Actions, variáveis protegidas no GitLab, etc.). Rotacione keys comprometidas imediatamente.

4. Identificar a API no catálogo

Você pode usar o UUID ou o nome/slug da API:

# Por UUID (legado)
export APIDEX_API_ID="550e8400-e29b-41d4-a716-446655440000"
apidex publish ./openapi.yaml --api 550e8400-e29b-41d4-a716-446655440000 ...

# Por nome ou slug (recomendado em CI)
export APIDEX_API_NAME="apiary-ms-auth"
apidex validate ./openapi.yaml --api-name apiary-ms-auth --api-key "$APIDEX_API_KEY"

Precedência: --api / APIDEX_API_ID > --api-name / APIDEX_API_NAME. Nomes legíveis como APIary MS Auth são normalizados para slug (apiary-ms-auth).

Configuração — variáveis e flags

| Variável de ambiente | Flag equivalente | Descrição | Default | |---|---|---|---| | APIDEX_API_KEY | --api-key | Service API key apk_* | — | | APIDEX_BASE_URL | --base-url | URL do integration-service | https://apidex.com.br/svc/integration/v1 | | APIDEX_API_ID | --api | UUID da API no catálogo (fluxo OpenAPI) | — | | APIDEX_API_NAME | --api-name | Nome ou slug da API no catálogo (ex.: apiary-ms-auth) | — | | APIDEX_MICROSERVICE_ID | --microservice-id / --id | UUID do microserviço no catálogo | — | | APIDEX_MCP_ID | --mcp-id / --id | UUID do servidor MCP no catálogo | — | | APIDEX_ENV | --env | Ambiente: dev, hml ou prod | dev | | — | --json | Saída estruturada JSON | false | | — | --gate-mode | Gate: block, warn ou off | block (validate/publish), off (diff) | | — | --min-score | Score mínimo de qualidade (0–100) | definido pelo backend |

Compatibilidade: as variáveis legadas APIARY_API_KEY, APIARY_BASE_URL e APIARY_API_ID ainda funcionam.

Comandos

OpenAPI (apidex publish|validate|diff)

apidex validate <spec>

Validação em duas camadas:

1. Local — parse YAML/JSON + checagens estruturais OpenAPI (sempre executada).
2. Remota — lint Spectral + diff via POST /ci/validate (quando APIDEX_API_KEY e --api estão definidos).

Exemplo — validação local (sem credenciais)

apidex validate ./openapi.yaml --local-only

Saída (sucesso, exit 0):

mode: local
openapi: 3.0.3
valid: true
Dica: defina APIDEX_API_KEY e --api para lint Spectral e diff remoto.

Exemplo — spec inválida

apidex validate ./spec-quebrada.yaml --local-only

Saída (falha, exit 1):

mode: local
valid: false

Issues locais:
  [error] /: Falha ao interpretar a spec (yaml): Nested mappings are not allowed...

Exemplo — validação completa com gate

apidex validate ./openapi.yaml \
  --api "$APIDEX_API_ID" \
  --env dev \
  --gate-mode block \
  --min-score 70

Saída (sucesso remoto, exit 0):

mode: local+remote
openapi: 3.0.3
valid: true
runId: run_abc123
score: 85 (min 70)
breaking: false
verdict: pass
engine: lint=spectral diff=oasdiff

apidex diff <spec>

Compara a spec local contra a versão ativa no ambiente informado.

Exemplo — diff em homologação

apidex diff ./openapi.yaml --api "$APIDEX_API_ID" --env hml

Saída (sem breaking, exit 0):

breaking: false
changes: 2
- {"type":"endpoint-added","path":"/v2/users","level":"non-breaking"}
- {"type":"description-changed","path":"/health","level":"non-breaking"}

Exemplo — bloquear pipeline em breaking changes

apidex diff ./openapi.yaml --api "$APIDEX_API_ID" --fail-on-breaking

Saída (com breaking, exit 1):

breaking: true
changes: 1
- {"type":"response-removed","path":"/users/{id}","level":"breaking"}

Flags úteis: --breaking-only, --json, --gate-mode block.

apidex publish <spec>

Envia a spec para ingestão e aguarda o pipeline (quality → breaking → gate).

Exemplo — publish em dev

apidex publish ./openapi.yaml \
  --api "$APIDEX_API_ID" \
  --env dev \
  --version 1.2.0 \
  --changelog "Deploy via CI — PR #42" \
  --idempotency-key "${GITHUB_SHA}" \
  --gate-mode block \
  --min-score 70

Saída (sucesso, exit 0):

jobId: job_xyz789
status: completed
phase: done
verdict: pass
version: 1.2.0
quality score: 88 (min 70)

Opções adicionais:

| Flag | Descrição | |---|---| | --no-wait | Dispara o job e retorna sem aguardar conclusão | | --auto-activate | Promove a versão para active quando o gate passa | | --timeout <s> | Timeout do polling (default: 180s) | | --poll-interval <s> | Intervalo entre consultas (default: 5s) |

Microserviços (apidex microservice publish|validate|diff)

Publica ou valida um manifest de microserviço no catálogo Apidex. O manifest descreve o repositório Git e metadados do serviço.

Exemplo de manifest (catalog/microservice.yaml):

name: payments-service
description: Serviço de pagamentos
repoUrl: https://github.com/acme/payments-service
branch: main
slug: payments-service

Validar (PR check)

apidex microservice validate ./catalog/microservice.yaml \
  --gate-mode block \
  --local-only   # só estrutura local, sem backend

Diff contra entrada existente

apidex microservice diff ./catalog/microservice.yaml \
  --microservice-id "$APIDEX_MICROSERVICE_ID" \
  --fail-on-breaking

Publicar (importação Git + análise opcional)

apidex microservice publish ./catalog/microservice.yaml \
  --idempotency-key "${GITHUB_SHA}" \
  --analyze \
  --gate-mode block \
  --timeout 300

Flags específicas: --analyze (dispara análise IA após importação), --reimport (força re-importação do repositório).

MCP (apidex mcp publish|validate|diff)

Publica ou valida um manifest de servidor MCP no catálogo Apidex.

Exemplo de manifest (catalog/mcp.yaml):

name: GitHub MCP
slug: github
description: Issues, PRs e repos
provider: GitHub
transport: stdio
endpoint: npx -y @modelcontextprotocol/server-github
tags: [git, devtools]
tools:
  - name: search_repositories
    description: Busca repositórios no GitHub

Validar

apidex mcp validate ./catalog/mcp.yaml --gate-mode block

Diff

apidex mcp diff ./catalog/mcp.yaml \
  --mcp-id "$APIDEX_MCP_ID" \
  --fail-on-breaking

Publicar

apidex mcp publish ./catalog/mcp.yaml \
  --idempotency-key "${GITHUB_SHA}" \
  --gate-mode block

Endpoints da API (integration-service)

| Fluxo | Operação | Endpoint | |---|---|---| | OpenAPI | publish | POST /v1/publish | | OpenAPI | status do job | GET /v1/publish/{jobId} | | OpenAPI | validate | POST /v1/ci/validate | | Microserviço | publish | POST /v1/ci/microservices/publish | | Microserviço | status do job | GET /v1/ci/microservices/publish/{jobId} | | Microserviço | validate | POST /v1/ci/microservices/validate | | Microserviço | diff | POST /v1/ci/microservices/diff | | MCP | publish | POST /v1/ci/mcp/publish | | MCP | status do job | GET /v1/ci/mcp/publish/{jobId} | | MCP | validate | POST /v1/ci/mcp/validate | | MCP | diff | POST /v1/ci/mcp/diff |

Gap conhecido (backend): os endpoints de microserviço e MCP ainda não estão implementados no apiary-integration-service (v0.2.0 do CLI já envia as requisições com o contrato acima). A validação local (--local-only) funciona offline. Quando o backend estiver disponível, os comandos remotos passam a operar sem alteração no CLI.

Exit codes e CI

| Exit code | Significado | |---|---| | 0 | Sucesso — spec válida, sem breaking (quando --fail-on-breaking), publish concluído | | 1 | Falha — spec inválida, gate bloqueado, breaking detectado, erro de API ou timeout |

Em pipelines CI/CD, o exit code é o mecanismo de gate: um exit 1 interrompe o job e impede merge/deploy. Por isso --fail-on-breaking e --gate-mode block são as flags mais usadas em pull requests.

Todos os comandos aceitam --json para parsing programático:

apidex diff ./openapi.yaml --api "$APIDEX_API_ID" --fail-on-breaking --json

GitHub Actions — receita completa (3 fluxos)

Copie este workflow para .github/workflows/apidex.yml:

name: Apidex — Governança (API + Microserviço + MCP)

on:
  pull_request:
    branches: [main]
    paths:
      - 'api/openapi.yaml'
      - 'catalog/microservice.yaml'
      - 'catalog/mcp.yaml'
  push:
    branches: [main]
    paths:
      - 'api/openapi.yaml'
      - 'catalog/microservice.yaml'
      - 'catalog/mcp.yaml'

env:
  APIDEX_BASE_URL: https://apidex.com.br/svc/integration/v1
  APIDEX_API_ID: ${{ vars.APIDEX_API_ID }}
  APIDEX_MICROSERVICE_ID: ${{ vars.APIDEX_MICROSERVICE_ID }}
  APIDEX_MCP_ID: ${{ vars.APIDEX_MCP_ID }}
  APIDEX_ENV: dev

jobs:
  validate-and-diff:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Instalar CLI Apidex
        run: npm install -g elvoro-apidex

      - name: OpenAPI — validar e diff
        env:
          APIDEX_API_KEY: ${{ secrets.APIDEX_API_KEY }}
        run: |
          apidex validate api/openapi.yaml --api "$APIDEX_API_ID" --gate-mode block
          apidex diff api/openapi.yaml --api "$APIDEX_API_ID" --fail-on-breaking

      - name: Microserviço — validar e diff
        env:
          APIDEX_API_KEY: ${{ secrets.APIDEX_API_KEY }}
        run: |
          apidex microservice validate catalog/microservice.yaml --gate-mode block
          apidex microservice diff catalog/microservice.yaml --fail-on-breaking

      - name: MCP — validar e diff
        env:
          APIDEX_API_KEY: ${{ secrets.APIDEX_API_KEY }}
        run: |
          apidex mcp validate catalog/mcp.yaml --gate-mode block
          apidex mcp diff catalog/mcp.yaml --fail-on-breaking

  publish:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Instalar CLI Apidex
        run: npm install -g elvoro-apidex

      - name: OpenAPI — publicar
        env:
          APIDEX_API_KEY: ${{ secrets.APIDEX_API_KEY }}
        run: |
          apidex publish api/openapi.yaml \
            --api "$APIDEX_API_ID" \
            --env dev \
            --version "${{ github.sha }}" \
            --idempotency-key "${{ github.run_id }}-api" \
            --gate-mode block

      - name: Microserviço — publicar
        env:
          APIDEX_API_KEY: ${{ secrets.APIDEX_API_KEY }}
        run: |
          apidex microservice publish catalog/microservice.yaml \
            --idempotency-key "${{ github.run_id }}-ms" \
            --analyze \
            --gate-mode block \
            --timeout 300

      - name: MCP — publicar
        env:
          APIDEX_API_KEY: ${{ secrets.APIDEX_API_KEY }}
        run: |
          apidex mcp publish catalog/mcp.yaml \
            --idempotency-key "${{ github.run_id }}-mcp" \
            --gate-mode block

Secrets e variáveis necessários no repositório:

| Nome | Tipo | Valor | |---|---|---| | APIDEX_API_KEY | Secret | apk_... | | APIDEX_API_ID | Variable | UUID da API no catálogo | | APIDEX_MICROSERVICE_ID | Variable | UUID do microserviço (opcional em primeiro publish) | | APIDEX_MCP_ID | Variable | UUID do servidor MCP (opcional em primeiro publish) |

GitLab CI (equivalente — OpenAPI)

apidex-governance:
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - api/openapi.yaml
  before_script:
    - npm install -g elvoro-apidex
  script:
    - apidex validate api/openapi.yaml --api "$APIDEX_API_ID" --gate-mode block
    - apidex diff api/openapi.yaml --api "$APIDEX_API_ID" --fail-on-breaking
  variables:
    APIDEX_BASE_URL: https://apidex.com.br/svc/integration/v1
    APIDEX_ENV: dev

apidex-publish:
  image: node:20
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - api/openapi.yaml
  before_script:
    - npm install -g elvoro-apidex
  script:
    - |
      apidex publish api/openapi.yaml \
        --api "$APIDEX_API_ID" \
        --version "$CI_COMMIT_SHORT_SHA" \
        --idempotency-key "$CI_PIPELINE_ID" \
        --gate-mode block
  variables:
    APIDEX_BASE_URL: https://apidex.com.br/svc/integration/v1
    APIDEX_ENV: dev

Configure APIDEX_API_KEY e APIDEX_API_ID como variáveis protegidas/mascaradas no GitLab.

GitLab CI — microserviço e MCP (trecho)

apidex-microservice:
  image: node:20
  rules:
    - changes: [catalog/microservice.yaml]
  before_script:
    - npm install -g elvoro-apidex
  script:
    - apidex microservice validate catalog/microservice.yaml --gate-mode block
    - apidex microservice publish catalog/microservice.yaml --analyze --idempotency-key "$CI_PIPELINE_ID"

apidex-mcp:
  image: node:20
  rules:
    - changes: [catalog/mcp.yaml]
  before_script:
    - npm install -g elvoro-apidex
  script:
    - apidex mcp validate catalog/mcp.yaml --gate-mode block
    - apidex mcp publish catalog/mcp.yaml --idempotency-key "$CI_PIPELINE_ID"

Solução de problemas

| Sintoma | Causa provável | O que fazer | |---|---|---| | API key inválida ou ausente (401) | Key incorreta, expirada ou não informada | Verifique APIDEX_API_KEY no secret do CI; confirme o prefixo apk_ | | Permissão insuficiente (403) | Key sem permissão ou sem allowProd | Revise permissões na tela API Keys; para --env prod, habilite allowProd | | Recurso não encontrado (404) | UUID da API errado ou API sem versão ativa no ambiente | Confirme APIDEX_API_ID; publique uma versão inicial antes de usar diff | | Spec inválida / issues locais | YAML malformado ou OpenAPI incompleto | Corrija a spec; use apidex validate --local-only para diagnóstico offline | | API key obrigatória | Comando diff/publish sem credencial | Defina APIDEX_API_KEY ou passe --api-key | | Timeout aguardando o job | Pipeline demorou além do --timeout | Aumente --timeout ou use --no-wait e consulte o job no app | | Diff vazio | Sem baseline (nenhuma versão ativa no ambiente) | Faça um publish inicial com --auto-activate |

Desenvolvimento

npm install
npm run build
npm test
node dist/bin.js --help
node dist/bin.js microservice validate fixtures/microservice-manifest.json --local-only
node dist/bin.js mcp validate fixtures/mcp-manifest.yaml --local-only

Links

• Site: https://apidex.com.br
• Documentação do produto: https://apidex.com.br/docs
• Pacote npm: npmjs.com/package/elvoro-apidex

Licença

MIT — Copyright © 2026 Elvoro IT Solutions