Api Documentation Template Github

Document ID: SOP-TR-OPS-4092
Effective Date: March 30, 2026
Version: 3.4.0
Review Cadence: Semi-Annual
Target Audience: API Product Managers, Technical Writers, Lead Software Architects, DevOps Engineers, and Open Source Program Office (OSPO) Personnel.

---

1. Executive Summary & Scope

1.1 Purpose

This Standard Operating Procedure (SOP) defines the institutional mandates, validation workflows, and release mechanisms for deploying, maintaining, and governing API documentation templates within Template Registry-managed GitHub repositories. It establishes a repeatable, high-reliability framework to ensure all public and internal API specifications achieve 100% compliance with OpenAPI 3.1.0 standards, semantic versioning, and zero-trust documentation security.

1.2 Scope

This operational policy governs all repositories hosted under the template-registry GitHub organization that serve as canonical templates for REST, GraphQL, and gRPC service definitions. Excluded from this scope are legacy SOAP endpoints governed by legacy documentation protocols (SOP-TR-LEG-102), though migration pathways to this standard must follow Section 5 of this document.

1.3 Regulatory & Compliance Framework

All generated API documentation templates must adhere to:

• OpenAPI Initiative (OAI) Specification 3.1.0
• ISO/IEC 27001:2022 (Information Security Management Systems - Annex A.14 System Acquisition, Development, and Maintenance)
• SOC 2 Type II (Trust Services Criteria for Security, Confidentiality, and Processing Integrity)
• GDPR/CCPA Data Minimization Principles (Prohibition of PII, internal IP, or hardcoded secrets in example payloads)

---

2. Prerequisites & Tool Requirements

2.1 Access Controls & Permissions

• GitHub Organization: Member of template-registry with Write permissions minimum on target template repositories; Admin permissions required for branch protection rule modifications.
• Identity & Access Management: Multi-Factor Authentication (MFA) strictly enforced via hardware token or FIDO2-compliant passkey. SSH keys must be Ed25519 standard.

2.2 Toolchain & Software Dependencies

• Git: Version 2.40.0 or greater.
• Node.js & npm: Node.js LTS (v20.x Hydrogen) and npm v10.x.
• Redocly CLI: Version 1.20.0+ (npm i -g @redocly/cli).
• Spectral (Stoplight): Version 6.11.0+ (npm i -g @stoplight/spectral-cli).
• Make: GNU Make 4.3+ for orchestrating local build pipelines.

---

3. Roles & Responsibilities (RACI Matrix)

---

4. Step-by-Step Operational Procedure

Phase 1: Repository Initialization & Structural Verification

• Clone the canonical base repository via secure SSH protocol: git clone git@github.com:template-registry/api-doc-template.git
• Initialize a distinct operational branch following the naming convention: feature/api-spec-[ticket-id] or hotfix/[ticket-id].
• Verify directory structure contains the required root files:
  • README.md (Template Usage Guidelines)
  • openapi.yaml or openapi.json (Canonical Specification)
  • .spectral.yaml (Linting Ruleset)
  • redocly.yaml (Rendering Configuration)
  • Makefile (Local build orchestration)
• Verify that .gitignore explicitly excludes local build artifacts, temporary lock files, and environment-specific caches.

Phase 2: Schema Modification & OpenAPI 3.1.0 Enforcement

• Update the info block within openapi.yaml, ensuring strict adherence to semantic versioning (major.minor.patch).
• Validate that all paths, parameters, request bodies, and responses contain exhaustive descriptions and localized operational examples.
• Ensure all mock payloads are strictly anonymized, free of institutional credentials, internal IP addresses, and simulated PII.
• Execute local Spectral linting to verify schema structural integrity: spectral lint openapi.yaml
• Verify zero errors or warnings are returned by the linting engine against the institutional ruleset.

Phase 3: CI/CD Pipeline & GitHub Actions Verification

• Inspect the workflow configuration file located at .github/workflows/api-docs-ci.yaml.
• Confirm that automated GitHub Actions triggers are configured for pull_request against main and push to main.
• Verify workflow steps include:
  1. Checkout code (actions/checkout@v4)
  2. Setup Node.js environment (actions/setup-node@v4)
  3. Install dependencies (npm ci)
  4. Run Redocly linting (npx @redocly/cli lint openapi.yaml)
  5. Build static HTML documentation bundle (npx @redocly/cli build-docs openapi.yaml -o dist/index.html)
  6. Publish preview documentation to GitHub Pages or ephemeral preview environment.
• Push local modifications to the remote origin: git push -u origin feature/api-spec-[ticket-id]

Phase 4: Peer Review & Institutional Sign-Off

• Open a Pull Request (PR) in GitHub utilizing the standard organizational PR template (.github/pull_request_template.md).
• Assign mandatory reviewers: One (1) Lead API Architect and One (1) Security & Compliance Auditor.
• Verify all automated CI/CD checks pass successfully (Green status across Spectral, Redocly, and security scanners).
• Obtain formal digital sign-off (Approval) from the Accountable role (Chief Operations Architect or designated delegate).
• Merge the pull request using the Squash and Merge strategy to maintain a linear, clean commit history on the main branch.

---

5. Quality Assurance & Verification Criteria

5.1 Audit Checklist

• Syntax Integrity: OpenAPI file passes strict JSON/YAML validation without parsing errors.
• Completeness Benchmark: 100% of endpoints feature explicit summary, description, and at least one 2xx response example.
• Security Scheme Definition: Authentication mechanisms (OAuth2, Bearer, ApiKey) are explicitly defined in the components/securitySchemes block.
• Link Verification: Zero broken internal references ($ref) within the schema or accompanying markdown guides.

5.2 Acceptance Benchmarks & Tolerances

• Linting Tolerance: Zero (0) Errors, Zero (0) Warnings under the institutional Spectral ruleset.
• Build Performance: Static documentation generation must complete in under 45 seconds within the GitHub Actions runner environment.
• Accessibility Standard: Rendered HTML documentation must achieve a minimum score of 95 on automated Lighthouse accessibility audits.

---

6. Practical Troubleshooting Scenarios

Scenario A: Spectral Linting Failure Due to Unresolvable External References ($ref)

• Symptom: The CI pipeline fails during the Spectral lint step with error code ERR_REF_RESOLVE: Can't resolve reference 'components/schemas/User.yaml' from 'openapi.yaml'.
• Immediate Corrective Action Protocol:
  1. Check relative path syntax in the $ref pointer. External component references must be relative to the root directory or correctly mapped in .spectral.yaml.
  2. Execute localized debug linting: npx @stoplight/spectral-cli lint openapi.yaml -v
  3. If utilizing modularized multi-file schemas, bundle the specification locally prior to linting to confirm flattening integrity: npx @redocly/cli bundle openapi.yaml -o dist/bundled.yaml --ext yaml
  4. Amend the reference path, commit changes, and force a pipeline re-run.

Scenario B: GitHub Actions Workflow Failure on Redocly Build

• Symptom: GitHub Actions reports Process completed with exit code 1 during the build-docs job, with logs indicating OpenAPI 3.1.0 schema version mismatch in older CLI versions.
• Immediate Corrective Action Protocol:
  1. Inspect the workflow file (.github/workflows/api-docs-ci.yaml) to verify the Redocly CLI version pin.
  2. Update the CLI dependency specification to the latest stable release: npx @redocly/cli@latest ...
  3. Ensure Node.js runtime environment in the workflow is set strictly to v20.x.
  4. Trigger a workflow re-dispatch from the GitHub Actions UI with debug logging enabled (ACTIONS_STEP_DEBUG=true).