How cloudflare/api-schemas works
Project type and purpose
• This is not a runtime application but an “API‐as‐code” repository: it holds the OpenAPI schemas for the Cloudflare API (both YAML and JSON variants), plus shared/common definitions.
• Its main purpose is to version, validate, lint, and publish API schemas as source artifacts that downstream tools (e.g., documentation generators, client‐SDK generators) can consume.
File structure
• Top‐level artifacts:
– openapi.yaml / openapi.json – the canonical API specification files
– common.yaml – reusable components (schemas, parameters) imported by the main spec
• CI/CD and automation:
– .github/workflows/semgrep.yml – security/static‐analysis scans on schema files
– .github/workflows/stainless.yml – policy checks (e.g., style/lint rules via Stainless)
– .redocly.lint-ignore.yaml – exceptions for the Redocly linter
• Supporting files:
– common.yaml is imported by openapi.yaml; openapi.json can be generated from the YAML or vice versa
– README.md describes the repository’s purpose; LICENSE governs usage
Key insights from README
• “Contains OpenAPI schemas for the Cloudflare API.”
• It’s a central source of truth for all API definitions—not a service implementation.
Main components
a. Repository (GitHub)
b. Schema source files (openapi.yaml, common.yaml)
c. CI/CD workflows (GitHub Actions runners)
d. Linters and Validators (Redocly CLI, Semgrep, Stainless)
e. Generated artifacts (openapi.json, versioned spec bundles)
f. Consumers: documentation site generator, SDK generators, downstream services/clients
Relationships & interactions
• Commits/PRs in GitHub → trigger GitHub Actions →
• Semgrep workflow scans YAML/JSON for security issues
• Stainless workflow enforces style/policy rules
• Redocly linter runs (locally or in CI) against openapi.yaml + common.yaml
• On successful validation, a CI job can publish or bundle artifacts (openapi.json, NPM package, CDN upload)
• Downstream tools (SDK generators, documentation sites) pull the published spec
Architectural patterns & principles
• Specification-as-code: treat API definitions like application code (versioned, reviewed, tested)
• Modular schemas: common.yaml houses shared components to keep the spec DRY
• CI-driven validation: gate every change with automated checks (security, style, compliance)
• Publish-on-merge: every merged PR produces consumable artifacts for downstream use
Final advice
• Be meticulous in naming each file or component—accuracy is critical for a spec repo.
• CI‐driven gates (lint, security, policy) that protect the canonical API definitions.
• Both the static structure (files and their imports) and the dynamic flows (CI triggers, publishing).
• Use legends or notes to explain any non‐obvious relationships (e.g., why common.yaml is separate).