Guia de Desenvolvimento

Configuração

# Clone e instale as dependências de desenvolvimento
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Instale o Spectral CLI (necessário para as etapas de linting)
npm install -g @stoplight/spectral-cli

make dev-install cria um virtualenv em .venv/ e instala o projeto com extras de desenvolvimento (pytest, ruff, mypy).

Variáveis de Ambiente

A validação ao vivo da API requer:

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

Sem essas variáveis, make validate recorre ao modo dry-run.

Executando o Pipeline

Pipeline Completo

make all
# Executa: download → validate → spectral-lint → reconcile → spectral-gate → release

Etapas Individuais

make download        # Buscar specs upstream
make validate        # Executar testes ao vivo na API (requer token de API)
make validate-dry    # Execução dry run (sem chamadas à API)
make spectral-lint   # Modo de descoberta Spectral nas specs originais
make reconcile       # Aplicar correções de ambos os relatórios
make spectral-gate   # Quality gate Spectral nas specs reconciliadas
make release         # Gerar pacote de release

Documentação

make docs-generate   # Regenerar docs/01-validation-report.mdx a partir dos relatórios
make docs            # Compilar o site de documentação completo
make docs-serve      # Servidor de desenvolvimento local com hot reload

Executando Testes

make test           # pytest com cobertura
make lint           # ruff check + verificação de formatação
make typecheck      # Verificação de tipos com mypy
make ci-test        # Todos os três (usado no CI)

Os hooks de pre-commit são executados automaticamente no commit, se instalados:

make pre-commit-install   # Instalar git hooks
make pre-commit           # Executar todos os hooks manualmente

Estrutura do Projeto

scripts/
  download.py           # Etapa 1: Buscar specs do F5
  validate.py           # Etapa 2: Testes ao vivo na API
  spectral_lint.py      # Etapa 3/5: Adaptador de linting Spectral
  reconcile.py          # Etapa 4: Aplicar correções nas specs
  release.py            # Etapa 6: Empacotar release
  generate_docs.py      # Gerar MDX a partir dos relatórios
  utils/
    auth.py             # Autenticação na API F5 XC
    constraint_validator.py  # Teste de restrições + tipos de Discrepancy
    report_generator.py      # Formatação de relatórios
    schemathesis_runner.py   # Orquestração de testes Schemathesis
    spec_loader.py           # E/S de specs + formatação JSON

config/
  validation.yaml       # Configuração do pipeline
  endpoints.yaml        # Endpoints base para testes ao vivo

spectral/
  functions/
    f5-path-params.js   # Função Spectral customizada

docs/                   # Documentação MDX Starlight
tests/                  # Suíte de testes pytest
release/specs/          # Saída: arquivos de spec reconciliados
reports/                # Saída: relatórios de validação e Spectral

Adicionando um Novo Método de Correção

Para adicionar uma nova correção automática Spectral ao reconciliador:

Adicione a regra ao .spectral.yaml com a severidade desejada.
Habilite a correção automática em config/validation.yaml sob spectral.auto_fix:
```
spectral:
  auto_fix:
    your-new-rule: true
```

Adicione o método de correção ao SpecReconciler em scripts/reconcile.py:

def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
    """Fix description."""
    # Modify spec in place
    # Return spec if changed, None if no change needed
    return spec

Registre-o no dispatcher _apply_spectral_fix:

spectral_fixers = {
    # ... existing fixers ...
    "spectral:your-new-rule": self._fix_your_rule,
}

Adicione testes cobrindo o novo método de correção.

Adicionando uma Nova Regra Spectral

Para adicionar uma regra Spectral customizada com uma função JavaScript:

Crie a função em spectral/functions/your-rule.js. Exporte uma função default que recebe (targetVal, options, context) e retorna um array de objetos {message, path}.

Registre-a em spectral-pipeline.yaml:

functions:
  - f5-path-params
  - your-rule

rules:
  your-rule:
    description: "What it checks"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: your-rule

Pipeline de CI

O workflow do GitHub Actions (validate-and-release.yml) é executado em:

Agendamento: Diariamente às 6h UTC
Push para main: Quando scripts/, config/ ou pyproject.toml são alterados
Disparo manual: Com opções para release forçada ou dry-run

O workflow possui quatro jobs:

validate — Baixa specs, executa validação, Spectral lint, reconcile, Spectral gate
check-release-needed — Compara hashes de conteúdo para decidir se uma release é necessária
release — Empacota e cria um GitHub Release (apenas se o conteúdo mudou)
update-docs — Regenera 01-validation-report.mdx e abre um PR se houver alterações

Um job notify cria uma issue no GitHub se qualquer job falhar.

Fluxo de Branches e PRs

Todas as alterações seguem: Issue -> Branch -> PR -> CI passa -> Merge.

Nomes de branches: feature/<issue>-desc, fix/<issue>-desc, docs/<issue>-desc
PRs devem referenciar uma issue (Closes #N na descrição)
Verificações de CI obrigatórias: Check linked issues e Lint Code Base
Squash merge preferido; branches são excluídas automaticamente após o merge

Consulte CONTRIBUTING.md para as regras completas do fluxo de trabalho.