Api Docs Html Template

SOP-DOC-092: API Documentation HTML Template

1. Document Control & Revision History

2. Executive Summary & Scope

This Standard Operating Procedure (SOP) defines the mandatory architectural schema and deployment lifecycle for HTML-based API documentation. The scope encompasses all RESTful and gRPC endpoints exposed to internal and external partners. Compliance with this document ensures technical parity, cross-browser compatibility, and adherence to security standards (OWASP API Security Top 10) by preventing the exposure of sensitive metadata in public-facing documentation.

3. Prerequisites & Tool Requirements

• Environment: Node.js (LTS v18+), NPM/Yarn.
• Templating Engine: Handlebars (HBS) or EJS for modular injection.
• Style Framework: Tailwind CSS 3.x (utility-first baseline) to ensure zero-runtime bloat.
• Access: Read-only access to the internal Git repository docs-templates-core.
• Compliance: Validated SSL/TLS certificate for documentation hosting environment.

4. Roles & Responsibilities (RACI Matrix)

5. Step-by-Step Operational Procedure

Phase 1: Environment Initialization

• Verify local workspace synchronization with main branch.
• Execute npm install to load documentation dependencies.
• Initialize documentation staging environment (npm run serve:docs).

Phase 2: Template Configuration

• Update metadata.json with correct versioning (Semantic Versioning 2.0).
• Inject OpenAPI/Swagger spec YAML file into the /src/data directory.
• Validate relative paths for CSS/JS assets within index.html headers.

Phase 3: Build & Deployment

• Execute npm run build to generate static assets.
• Run npm run audit to detect injection vulnerabilities in template dependencies.
• Deploy to designated S3 bucket/CDN edge location via CI/CD pipeline.

6. Quality Assurance & Verification Criteria

• Loading Threshold: Page content must achieve a Lighthouse performance score of ≥ 95.
• Broken Link Audit: Zero 404 responses detected during automated crawling.
• Accessibility: Full compliance with WCAG 2.1 AA standards; all images/diagrams must include ARIA labels.
• Data Masking: Verification that no production credentials (e.g., Authorization: Bearer <TOKEN>) are present in example request payloads.

7. Practical Troubleshooting Scenarios

Scenario A: Build Failure (Dependency Mismatch)

• Symptom: npm run build exits with code 1 due to node_modules incompatibility.
• Corrective Action: Delete node_modules and package-lock.json. Execute npm cache clean --force, then re-run npm install.

Scenario B: Rendering Failure (Schema Syntax)

• Symptom: Documentation page fails to render the OpenAPI endpoint list.
• Corrective Action: Validate the source YAML file using swagger-cli validate. Ensure no trailing commas or invalid character escaping in parameter descriptions.

Scenario C: Asset Timeout (CDN Propagation)

• Symptom: Updated documentation shows cached, stale version.
• Corrective Action: Execute cache invalidation for the target path via CloudFront/Cloudflare API. Verify header Cache-Control: no-cache is active on the origin server.