How vapor/api-docs works
Project type and purpose
• This is an open-source tooling project whose sole responsibility is to generate and publish the API documentation for Vapor-based repos.
• It does not contain a customer-facing application; rather, it provides Swift scripts (generate-api-docs.swift, generate-package-api-docs.swift) and GitHub Actions workflows that, on every release in a Vapor repo, pull this tool in and run it to produce updated docs.
File structure
• .github/workflows/build-and-deploy-docs-workflow.yml & deploy-api-docs.yml – define CI/CD pipeline steps when a new release is cut.
• generate-api-docs.swift & generate-package-api-docs.swift – core Swift scripts that crawl repositories, render Markdown/DocC, and emit static HTML.
• index.html, error.html, theme-settings.json, images/ – static assets and theme configuration used by the generated docs site.
• stack.yaml – configuration for building/running the Swift (or Haskell-stack) environment to execute the scripts.
README for additional insights
• The README confirms that on each tagged release in any Vapor repo, a GitHub Action boots this repo’s scripts on a server, generates the docs, and publishes them to https://api.vapor.codes.
Main components & their interactions
a. Source Repositories (any Vapor project)
b. GitHub Actions workflows in each source repo (on “release” event)
c. This API-docs-generator repo – checked out by the workflow
d. Swift scripting environment (Docker/Mac builder, installed via stack.yaml)
e. Documentation Server / Hosting (the target of deploy step; serves at api.vapor.codes)
f. End Users (developers browsing the API docs site)
Data Flow & Sequence:
1. Developer creates a new Release tag in a Vapor repo.
2. GitHub Actions in that repo triggers the “build-and-deploy-docs-workflow.”
3. The workflow clones this api-docs-generator repo.
4. It spins up the Swift runtime (via stack.yaml) and runs generate-api-docs.swift (or generate-package-api-docs.swift).
5. Scripts produce static HTML (using index.html, theme-settings.json, images/, error.html).
6. The “deploy-api-docs.yml” job uploads the static site to the Documentation Server (e.g., S3/CloudFront or custom host).
7. End users view fresh docs at api.vapor.codes.
Key architectural patterns and design principles
• CI/CD pipeline: separation of “build” (generate static assets) and “deploy” phases.
• Immutable infrastructure principle: on each release, you spin up a fresh environment via GH Actions.
• Static site generation: all docs are rendered ahead-of-time, no server-side rendering at request time.