How yext/openapi works
Project type and purpose
• This repository is an “OpenAPI specification” library for the Yext API.
• It is not a running application but a collection of machine-readable API definitions in both JSON and YAML formats.
• Its purpose is to define, validate, generate code for, and publish the API surface of the Yext platform.
File structure
• Top-level:
• .github/workflows/main.yml – CI pipeline
• LICENSE, README.md
• json/ – each file is a complete OpenAPI JSON spec for one API segment
• yaml/ – the same specs in YAML format
• There are no “src” or “bin” folders because this is a spec-only project.
• CI config implies linting, formatting, generation, and/or publication steps.
README
• Single line: “OpenAPI specification for the Yext API.”
Main components
a. Spec repository (GitHub)
• Directory of JSON and YAML definitions
• Version control (Git)
b. Continuous Integration (GitHub Actions)
• Lint/validate step (e.g., Spectral or Swagger CLI)
• Round-trip conversion between JSON and YAML, if used
• Code generation step (e.g., openapi-generator)
• Documentation generation (e.g., Redoc, Swagger UI)
• Publication/deployment (e.g., push docs to static site or API portal)
c. Output artifacts
• Generated client/server SDKs
• Rendered API documentation
d. External consumers
• Developers (who consume docs or SDKs)
• Downstream services that will integrate with the Yext API
• Hosting environment for docs (e.g., GitHub Pages, CDN)
Relationships and interactions
• A developer pushes changes to the JSON or YAML folder →
• GitHub Actions triggers →
• Step 1: Validate all specs
• Step 2: (Optionally) convert/ensure sync between JSON and YAML
• Step 3: Generate SDKs or schemas
• Step 4: Build static documentation site
• Step 5: Deploy docs and artifacts to a hosting target or package registry
• Consumers fetch SDK packages or browse the published docs
Architectural patterns and principles
• Single source of truth: the OpenAPI files in YAML and JSON
• CI/CD pipeline that enforces quality, generates code and docs automatically
• Separation of concerns: specs (input) vs. processes (CI tasks) vs. outputs (artifacts)
• Idempotent builds: pipeline always recreates artifacts from specs
Additional guidance
• Major interactions (e.g., “push to repo triggers workflow,” “artifact uploaded to CDN”)