How sashi-u/swagger-spec works
Project type and purpose
• This is an open-source specification repository for the OpenAPI Specification (OAS). Its “runtime” is purely in document form: Markdown sources of the spec, schema files (JSON/YAML), proposal documents, build and validation scripts, and CI/CD pipelines. There is no user-facing application; the primary function is to produce published, machine-readable API descriptions and human-readable HTML documentation, validate schema conformance, and manage versioned/specification proposals.
File structure
• Top-level directories and files:
• versions/: Markdown source of each released spec version
• proposals/: feature‐and‐extension proposals structured by topic
• _archive_/: historical schema files (JSON/YAML) for older spec versions
• scripts/: shell, PowerShell, Node (mjs) scripts for generating HTML, testing schemas, publishing, version management
• tests/: automated tests for the md2html toolchain
• .github/workflows/: CI/CD pipelines (validate markdown, schema tests, publishing, sync branches)
• package.json / package-lock.json: Node dependencies (Vitest, YAML parsers, etc.)
• README.md, CONTRIBUTING.md, IMPLEMENTATIONS.md, style-guide.md, etc.: core project documentation
README for additional insights
• The README confirms the repository’s role in hosting Markdown sources of the specification and directing readers to the HTML render site. It mentions use cases (interactive documentation, code generation, test automation) and points at IMPLEMENTATIONS.md for tooling by others.
a. Main components
• GitHub Repository (source of truth)
• Contributors & TSC (people pushing PRs against versions/, proposals/, scripts/)
• CI/CD (GitHub Actions workflows)
• Build/Validation Scripts (scripts/md2html/, schema-publish.sh, schema-test-coverage.mjs, validate.mjs)
• Markdown Sources (versions/*.md, proposals/*)
• Schema Files (_archive_/schemas, schemas generated in-pack)
• Test Runner (Vitest, markdownlint)
• Output Artifacts (HTML docs via md2html, published schemas via schema-publish)
• External Services (Respec for HTML, npm registry, GitHub Pages or spec.openapis.org)
b. Relationships and data flow
1. Contributors push commits to branches →
2. GitHub Actions trigger workflows:
• validate-markdown: runs markdownlint on versions/, proposals/
• schema-tests: runs schema-test-coverage scripts against _archive_/schemas/**
• respec: builds HTML using md2html and Respec templates
• schema-publish: publishes updated schemas to a registry or spec site
• sync-dev-to-vX.Y-dev / sync-main-to-dev: automates branch synchronization
3. Scripts read Markdown sources and schema definitions, run tests, and generate outputs
4. Test runner (Vitest) executes unit tests for md2html and schema coverage
5. Successful builds deploy HTML and schema artifacts to spec.openapis.org or GitHub Pages
c. Architectural patterns and principles
• Static documentation pipeline (input = Markdown + schemas → processing → HTML / JSON outputs)
• CI/CD as the orchestration layer
• Single repository monorepo for spec, proposals, tooling, and tests
• Clear separation between source (versions/, proposals/) and build outputs (deployed docs)
• Extensibility via proposals folder and modular scripts
d. Key technologies and frameworks
• GitHub Actions for CI/CD
• Node.js scripts (ESM .mjs) for md2html conversion and schema coverage
• Bash / PowerShell helpers for release branching and porting (scripts/*.sh, *.ps1)
• Vitest for JavaScript testing
• markdownlint for enforcing style
• Respec (via md2html) to generate HTML from OpenAPI Markdown
Detailed, essential elements to capture
• Repository structure: versions/, proposals/, _archive_/, scripts/, tests/, .github/workflows
• CI workflows and their triggers (validate-markdown, schema-tests, respec, schema-publish, sync)
• Script functions: md2html conversion, schema coverage, branch management
• Test suite: markdownlint, Vitest tests under tests/md2html
• Output artifacts and destinations: HTML docs, published JSON/YAML schema files