Api Documentation Example Github

SOP-ENG-702: API Documentation Lifecycle Management (GitHub-Centric)

1. Document Control & Revision History

2. Executive Summary & Scope

This SOP defines the institutional standard for developing, publishing, and maintaining API documentation within the GitHub ecosystem. This document ensures that all externally facing and internal APIs comply with OpenAPI Specification (OAS) 3.0+ standards. The scope encompasses all repositories tagged as api-service within the enterprise GitHub organization, mandating automated CI/CD pipeline integration and semantic versioning compliance.

3. Prerequisites & Tool Requirements

• Access Requirements: Enterprise GitHub account with Write access to the repository; Read/Write access to the documentation-deploy service account.
• Software Requirements:
  • Node.js v18.x or higher.
  • Redocly CLI or Swagger-CLI for validation.
  • Prettier for syntax standardization.
• Documentation Standards: Proficiency in Markdown and YAML/JSON schema definitions.
• Hardware/Environment: Secure workstation with hardware-backed MFA (Multi-Factor Authentication).

4. Roles & Responsibilities (RACI Matrix)

5. Step-by-Step Operational Procedure

Phase 1: Preparation and Environment Setup

• Initialize documentation branch (docs/feat-api-vX.Y) from main.
• Confirm local installation of redocly CLI via npm install -g @redocly/cli.
• Pull the latest enterprise linting configuration file from the /shared-standards repo.

Phase 2: Documentation Drafting

• Define API paths in /docs/openapi.yaml adhering to the enterprise schema.
• Update README.md in the root directory to include a reference link to the new endpoint documentation.
• Ensure all code snippets and curl examples are verified for operational accuracy.

Phase 3: Validation and Quality Control

• Execute redocly lint docs/openapi.yaml and verify zero errors/warnings.
• Run npm run test:docs to ensure internal cross-references are valid.
• Perform a peer code review via GitHub Pull Request, tagging the Lead Engineer.

Phase 4: Deployment and Verification

• Merge PR into main after secondary validation.
• Monitor GitHub Actions docs-deploy workflow for successful build completion.
• Verify endpoint visibility on the enterprise developer portal.

6. Quality Assurance & Verification Criteria

• Syntax Compliance: 100% pass rate on openapi.yaml via linting tools.
• Broken Link Threshold: Zero broken links (internal/external) allowed.
• Naming Conventions: All endpoints must utilize kebab-case for path segments; parameter descriptions must exceed 20 characters for clarity.
• Acceptance Benchmark: Documentation must be rendered successfully on the staging environment prior to production promotion.

7. Practical Troubleshooting Scenarios

Scenario A: OpenAPI Linting Errors

• Failure: redocly lint returns 40+ structural errors due to incorrect schema hierarchy.
• Corrective Action: Immediately revert to the last stable state using git reset --hard. Consult the enterprise-schema-library repository for the correct boilerplate and re-map current parameters to the approved global definitions.

Scenario B: GitHub Actions Deployment Failure

• Failure: The CI/CD pipeline fails during the build-docs step with a 403 Forbidden or 500 error.
• Corrective Action: Check the repository Secrets (specifically DOCS_DEPLOY_TOKEN). Rotate the token if expired. Verify that the GitHub App has repository access permissions to the documentation hosting bucket (S3/CloudFront).

Scenario C: Outdated API Reference

• Failure: Deployed documentation shows obsolete endpoints not present in the current production build.
• Corrective Action: Trigger an emergency clean build via the GitHub Action workflow settings to purge the CDN cache. Audit the main branch versioning to ensure the build pipeline is not pointing to an old release tag.