Guia de Desenvolvimento

Este guia descreve o fluxo de trabalho de desenvolvimento para o Pipeline de Enriquecimento de API F5 XC.

Início Rápido

Configuração Inicial

# Clone o repositório
git clone https://github.com/f5-sales-demo/api-specs-enriched.git
cd api-specs-enriched

# Crie o ambiente virtual e instale as dependências
make install

# Instale os hooks do pre-commit
make pre-commit-install

# Baixe as specs e execute o pipeline
make build

# Visualize a documentação localmente
make serve

Desenvolvimento Diário

# Reconstrução rápida (usa specs em cache)
make rebuild

# Execute todas as verificações de qualidade
make pre-commit-run

# Visualize a documentação
make serve

Visão Geral da Arquitetura

Design de Duas Pastas

┌─────────────────────┐     ┌─────────────────────────────┐
│   specs/original/   │────▶│   docs/specifications/api/  │
│   (SOMENTE LEITURA) │     │   (GERADO)                  │
│   - Baixado         │     │   - Specs de domínio        │
│   - Gitignored      │     │   - Spec mestre             │
│   - Cache ETag      │     │   - GitHub Pages            │
└─────────────────────┘     └─────────────────────────────┘

Fluxo do Pipeline

Download (ETag) → Enriquecer → Normalizar → Mesclar → Lint → Servir
     │                │             │           │        │
     ▼                ▼             ▼           ▼        ▼
 270 specs       Identidade    Corrigir     23 domínios  Spectral
               + Gramática      refs       + Mestre      regras

Estrutura de Diretórios

Diretório	Finalidade	Status no Git
specs/original/	Specs fonte do F5	Gitignored
specs/discovered/	Saída da descoberta de API	Rastreado (openapi.json, session.json)
docs/specifications/api/	Specs de domínio geradas	Gitignored
scripts/	Scripts Python do pipeline	Rastreado
config/	Configuração do pipeline	Rastreado
reports/	Relatórios gerados	Gitignored

Padrões de Fluxo de Trabalho

1. Fluxo de Trabalho de Descoberta

Pré-requisitos:

• Conexão VPN com o ambiente F5 XC
• Credenciais de API válidas

# Configure as credenciais
export F5XC_API_URL="https://your-tenant.console.ves.volterra.io/api"
export F5XC_API_TOKEN="your-api-token"

# Execute a descoberta
make discover

# Visualize os resultados
jq '.statistics' specs/discovered/session.json

# Faça commit para CI/CD
make push-discovery

A descoberta captura:

• Campos obrigatórios/opcionais reais
• Valores de enum de respostas em produção
• Valores padrão
• Validações de padrão
• Exemplos de resposta

2. Fluxo de Trabalho de Release

Os releases são automatizados:

1. Agendamento diário (6h UTC) ou push para main aciona o fluxo
2. Verificação de ETag determina se as specs F5 foram alteradas
3. O pipeline processa e enriquece as specs
4. Versão calculada a partir das tags git: git describe --tags --abbrev=0
5. Commit direto + tag criada (sem PR de incremento de versão)
6. GitHub Release criado com changelog
7. Documentação implantada no GitHub Pages

Regras de Incremento de Versão:

Condição	Tipo de Incremento	Exemplo
[major] no commit	Major	1.0.0 → 2.0.0
BREAKING CHANGE no commit	Major	1.0.0 → 2.0.0
Nova spec de domínio adicionada	Minor	1.0.0 → 1.1.0
Qualquer outra alteração	Patch	1.0.0 → 1.0.1

3. Fluxo de Trabalho de Desenvolvimento

# Crie um branch de funcionalidade
git checkout -b feature/my-change

# Faça alterações na configuração ou nos scripts

# Teste localmente
make pipeline
make lint

# Faça commit (os hooks do pre-commit são executados automaticamente)
git add .
git commit -m "feat: add new enrichment rule"

# Envie e crie um PR
git push -u origin feature/my-change
gh pr create

Aprofundamento na Descoberta

O que é Descoberta?

A descoberta explora a API F5 XC ativa para encontrar:

• Restrições não documentadas: Campos obrigatórios não marcados no OpenAPI
• Valores de enum reais: Valores reais vistos em produção
• Comportamentos padrão: Valores aplicados pelo servidor quando campos são omitidos
• Padrões de resposta: Formatos reais de dados

Configuração de Descoberta

config/discovery.yaml

discovery:
  exploration:
    namespaces:
      - "system"
      - "shared"
    methods:
      - "GET"
      - "OPTIONS"
    max_endpoints_per_run: 500

  schema_inference:
    sample_size: 3
    detect_patterns: true
    detect_constraints: true

Extensões de Descoberta

A descoberta adiciona extensões x-discovered-* às specs:

{
  "properties": {
    "name": {
      "type": "string",
      "x-discovered-required": true,
      "x-discovered-pattern": "^[a-z][a-z0-9-]*$",
      "x-discovered-examples": ["my-app", "prod-lb"]
    }
  }
}

Relatório de Análise de Restrições

reports/constraint-analysis.md

make constraint-report

Processo de Release

Conteúdo do Pacote de Release

f5xc-api-specs-v1.0.14.zip
├── openapi.json       # Spec mestre combinada
├── openapi.yaml       # Formato YAML
├── domains/           # Specs de domínio individuais
│   ├── api_security.json
│   ├── load_balancer.json
│   └── ...
├── index.json         # Metadados
├── CHANGELOG.md       # Notas de release
└── README.md          # Instruções de uso

Acionamento Manual do Fluxo de Trabalho

gh workflow run sync-and-enrich.yml
gh run watch

Guia de Configuração

Configuração de Enriquecimento

config/enrichment.yaml

enrichment:
  branding:
    replacements:
      "Volterra": "F5 Distributed Cloud"
      "VES": "F5 XC"

  acronyms:
    API: "Application Programming Interface"
    DNS: "Domain Name System"

  grammar:
    enabled: true
    language_tool: true

Configuração de Normalização

config/normalization.yaml

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

Regras de Lint do Spectral

config/spectral.yaml

extends:
  - spectral:oas

rules:
  operation-operationId: error
  operation-tags: warn

Extensões OpenAPI

O pipeline de enriquecimento utiliza extensões de fornecedor para incorporar metadados de validação e valores padrão.

Categorias de Extensão

Extensão	Significado	Implicação
x-f5xc-server-default	O servidor da API F5 XC aplica este valor quando o campo é omitido	O campo é opcional; omiti-lo produz o comportamento padrão documentado
x-f5xc-recommended-value	O console web F5 XC pré-preenche este valor para novos recursos	O campo não tem padrão do servidor, mas este valor representa a configuração típica
x-f5xc-recommended-oneof-variant	O console F5 XC pré-seleciona esta variante OneOf	Identifica a escolha típica quando existem múltiplas opções mutuamente exclusivas
x-f5xc-conflicts-with	Lista outras propriedades que não podem ser usadas em conjunto com este campo	A propriedade faz parte de um grupo OneOf; apenas uma das propriedades conflitantes pode ser especificada

Extensões de Campo Obrigatório

Extensão	Origem	Finalidade
x-ves-required: "true"	Spec original F5 XC	Campo requer valor não-zero/não-vazio
x-f5xc-required-for	Pipeline de enriquecimento	Status de obrigatoriedade específico por contexto

Contextos de x-f5xc-required-for:

• create: Obrigatório ao criar o recurso
• update: Obrigatório ao atualizar o recurso
• minimum_config: Obrigatório para configuração mínima viável

Extensões de Valor Padrão e OneOf

Extensão	Finalidade
x-f5xc-server-default: true	Marca padrões aplicados pelo servidor
x-f5xc-recommended-value	Valor pré-preenchido pelo console F5 XC
x-f5xc-recommended-oneof-variant	Variante OneOf recomendada
x-f5xc-conflicts-with	Exclusividade mútua com outras propriedades OneOf

x-f5xc-server-default

Tipo: boolean

Quando true, indica que o valor default acompanhante é aplicado pelo servidor da API F5 XC. Campos com esta extensão podem ser omitidos com segurança das requisições de API — o servidor aplica o padrão automaticamente.

use_http2:
  type: boolean
  default: false
  x-f5xc-server-default: true

x-f5xc-recommended-value

Tipo: any (corresponde ao tipo do campo)

Especifica um valor que o console web F5 XC utiliza como padrão pré-preenchido. Este valor não é aplicado pelo servidor, mas representa a configuração inicial típica para novos recursos criados via console.

timeout:
  type: integer
  x-f5xc-recommended-value: 3

x-f5xc-recommended-oneof-variant

Tipo: object (mapa de nome do grupo para nome da variante)

Para schemas com grupos de campos mutuamente exclusivos, identifica qual variante é a escolha padrão ou mais comum. A chave é o nome do grupo OneOf e o valor é o nome do campo da variante recomendada.

healthcheckCreateSpecType:
  type: object
  x-f5xc-recommended-oneof-variant:
    health_check: "http_health_check"

x-f5xc-conflicts-with

Tipo: array de strings

Adicionado: v3.2.0 (Issue #494)

Declara relações de exclusividade mútua entre membros de um grupo OneOf. Derivado automaticamente das extensões x-ves-oneof-field-*. Isso permite que ferramentas downstream (Terraform, CLI, MCP) validem conflitos no nível do schema em vez de em tempo de execução.

host_header:
  type: string
  x-f5xc-conflicts-with: ["use_origin_server_name"]

use_origin_server_name:
  type: object
  x-f5xc-conflicts-with: ["host_header"]

Casos de uso:

• Provedores Terraform podem gerar regras de validação
• Ferramentas CLI podem alertar sobre combinações de campos conflitantes
• Assistentes de IA podem gerar configurações OneOf corretas
• Extensões de IDE podem fornecer autocompleção com reconhecimento de conflitos

Origem: Derivado automaticamente das extensões nativas F5 x-ves-oneof-field-* durante o enriquecimento do pipeline.

Implicações das Regras de Validação

O enriquecedor inspeciona x-ves-validation-rules para inferir o status de obrigatoriedade:

Regra	Implicação
ves.io.schema.rules.message.required: "true"	Campo é obrigatório
ves.io.schema.rules.uint32.gte: N	Se N >= 1 e sem padrão do servidor, campo é obrigatório
ves.io.schema.rules.repeated.min_items: N	Se N >= 1, array requer pelo menos N itens
ves.io.schema.rules.string.min_bytes: N	Se N >= 1, string requer pelo menos N bytes

Recursos com Padrões Aplicados pelo Servidor

Alguns recursos aceitam specs vazias porque o servidor aplica os padrões:

Recurso	Padrões Aplicados pelo Servidor
app_firewall	monitoring: \{\}, default_detection_settings: \{\}
rate_limiter	limits: [], user_identification: []
api_definition	swagger_specs: [], api_groups padrão
healthcheck	jitter: 0, jitter_percent: 0, padrões aninhados de http_health_check

Para esses recursos, x-f5xc-required-for.create pode ser false mesmo quando x-ves-required é true.

Padrões de Valores Padrão

Padrão	Tipo	Exemplo
\{\}	Objeto vazio (seleção de opção)	monitoring: \{\}
[]	Array vazio	expected_status_codes: []
0	Numérico	jitter: 0
""	String	expected_response: ""
false	Booleano	use_http2: false

Adicionando Padrões Descobertos

1. Crie o recurso no F5 XC com spec mínima via API
2. Leia de volta o recurso para ver os valores aplicados pelo servidor
3. Documente os padrões em config/discovered_defaults.yaml
4. Execute o pipeline: make pipeline
5. Verifique com: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

Solução de Problemas

Pre-commit Demora Muito

O pipeline é executado a cada commit para garantir consistência. Para commits de trabalho em andamento:

git commit --no-verify -m "WIP: work in progress"
# Execute antes do commit final: make pre-commit-run

Descoberta Falha

# Verifique a VPN
ping your-tenant.console.ves.volterra.io

# Verifique as credenciais
echo $F5XC_API_TOKEN | head -c 10

# Verifique o formato da URL da API
echo $F5XC_API_URL
# Formato: https://tenant.console.ves.volterra.io/api

Erros de Lint nas Specs Geradas

# Verifique o relatório de lint
cat reports/lint-report.json | jq '.errors'

Corrija os problemas na configuração de enriquecimento/normalização, não nos arquivos de saída.

Sistema de Versão

A versão é derivada das tags git (ex.: v2.0.38), eliminando condições de corrida que causavam conflitos de merge em PRs concorrentes.

# A versão é calculada dinamicamente a partir das tags git
from scripts.utils.version_calculator import get_version_from_tags
version = get_version_from_tags()  # Retorna "2.0.38"

Specs Ausentes Após Clone

As specs geradas estão no gitignore:

make build  # Baixa e gera tudo

Arquivo Grande Bloqueado

Adicione a exclusão ao .pre-commit-config.yaml:

- id: check-added-large-files
  exclude: ^path/to/large/file\.json$

Referência Rápida

Alvos do Make

Alvo	Descrição
make build	Build completo (download + pipeline)
make rebuild	Reconstrução rápida (ignora download)
make download	Baixa specs (com cache ETag)
make download-force	Força o download
make pipeline	Executa o pipeline de enriquecimento
make lint	Lint com Spectral
make serve	Servidor local de documentação
make discover	Descoberta de API (requer VPN)
make push-discovery	Faz commit dos dados de descoberta
make clean	Remove arquivos gerados
make pre-commit-run	Executa todas as verificações de qualidade

Variáveis de Ambiente

Variável	Finalidade
F5XC_API_URL	URL da API do tenant F5 XC
F5XC_API_TOKEN	Token de autenticação da API

Arquivos Principais

Arquivo	Finalidade
.etag	Último ETag baixado
CHANGELOG.md	Changelog gerado automaticamente
config/enrichment.yaml	Regras de enriquecimento
config/normalization.yaml	Regras de normalização
config/discovery.yaml	Configurações de descoberta
config/spectral.yaml	Regras de lint
scripts/utils/version_calculator.py	Cálculo de versão baseado em tags

Nota: A versão é derivada das tags git (ex.: v2.0.38), não de um arquivo .version.