OpenAPI Specification Repository - Deploy & Usage Guide

This guide covers local development, validation, and contribution workflows for the OpenAPI Specification repository. This repository contains the canonical Markdown sources for the OpenAPI Specification (OAS) standards.

1. Prerequisites

To work with the specification sources locally, you need:

• Git (2.20+) for version control
• Node.js (16.x or higher) to run the markdown validation tooling
• npm (8.x or higher) or yarn for package management
• A GitHub account (required for submitting issues, discussions, or pull requests)
• A text editor with Markdown support (VS Code with the "OpenAPI (Swagger)" extension recommended)

2. Installation

Clone the repository and install validation dependencies:

# Clone the repository
git clone https://github.com/OAI/OpenAPI-Specification.git
cd OpenAPI-Specification

# Install markdown validation and link checking tools
npm install

If you're using a fork for contributions, add the upstream remote:

git remote add upstream https://github.com/OAI/OpenAPI-Specification.git

3. Configuration

Minimal configuration is required for local development:

# Configure Git identity (required for commits)
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Sync your fork with upstream (recommended before starting work)
git fetch upstream
git checkout main
git merge upstream/main

No environment variables, API keys, or external service configurations are required to view or validate the specification files.

4. Build & Run

The primary "build" action for this repository is validating the Markdown specification files and checking for broken internal links.

Validate Markdown

Run the validation suite locally (mirrors the GitHub Actions validate-markdown workflow):

# Validate all specification markdown files
npm run validate

# Check for broken links in the repository
npm run check-links

View Specification Versions

The specification sources are located in the versions/ directory. View them directly:

# View a specific version (example: 3.1.0)
cat versions/3.1.0.md

# Or serve the repository locally to preview HTML renderings
npx serve .
# Then navigate to http://localhost:3000/versions/ to view files

Run GitHub Actions Locally (Optional)

To test the validation workflow locally before pushing:

# Using act (https://github.com/nektos/act) to run GitHub Actions locally
act -j validate-markdown

5. Deployment

This section covers how the specification is published and how to deploy custom instances.

Official Specification Deployment

The OpenAPI Specification is automatically published to the authoritative location:

• Production URL: https://spec.openapis.org/
• Source: The main branch Markdown files in the versions/ directory
• Mechanism: Maintainers merge approved changes into main, which triggers publication to the specification website via the release process documented in CONTRIBUTING.md

Deploying a Fork (GitHub Pages)

To host your own version of the specification documentation:

1. Enable GitHub Pages in your fork's repository settings (Settings > Pages)
2. Source: Select Deploy from a branch → main branch → / (root)
3. Access: Your specification will be available at https://<username>.github.io/OpenAPI-Specification/

Release Process (Maintainers Only)

New specification versions follow this deployment workflow:

1. Changes are merged into the main branch via the TSC review process
2. Releases are tagged following semantic versioning
3. The releases page documents release notes
4. HTML renderings are regenerated and published to spec.openapis.org

6. Troubleshooting

Validation Failures

Issue: npm run validate fails with markdown syntax errors.
Solution:

• Ensure Markdown files use consistent heading levels
• Check that internal links use relative paths (e.g., ./versions/3.1.0.md not absolute URLs)
• Verify YAML code blocks in examples are properly fenced with ```yaml

Broken Link Errors

Issue: Link checker reports 404s for external URLs.
Solution:

• Some external links may be transient; retry the check
• If a link is permanently broken, update it in the Markdown source or report it as an issue
• Use https:// protocol for all external references

Syncing with Upstream

Issue: "Your branch is behind 'upstream/main'" when creating PRs.
Solution:

git fetch upstream
git rebase upstream/main
git push origin main --force-with-lease

Viewing Rendered Specifications

Issue: Markdown renders differently locally than on spec.openapis.org.
Solution:

• The official site uses specific rendering tools (likely ReSpec or similar) that may differ from GitHub's Markdown preview
• For accurate preview, refer to the authoritative HTML renderings rather than raw Markdown
• Check the examples for implementation references

Participation Access

Issue: Unable to join weekly TSC calls.
Solution:

• Verify you're using the correct calendar link
• No special invitation is required; calls are open to the community
• Check the discussions for async participation if you cannot attend live sessions