Api Documentation Templates

STANDARD OPERATING PROCEDURE: Enterprise API Documentation Lifecycle Management

Document ID: SOP-OPS-ENG-409
Effective Date: October 24, 2023
Classification: Internal Operations / Technical Standard

---

1. Document Control & Revision History

---

2. Executive Summary & Scope

2.1 Clinical Statement of Operational Boundaries

This Standard Operating Procedure (SOP) defines the mandatory lifecycle for the creation, validation, deployment, and decommissioning of Application Programming Interface (API) documentation across all enterprise digital ecosystems. The operational boundary encompasses all internal, partner-facing, and public RESTful, GraphQL, and gRPC endpoints managed by engineering and product business units.

2.2 Regulatory Standards & Compliance

All API documentation produced under this SOP must maintain strict compliance with the following frameworks:

• OpenAPI Specification (OAS) v3.1.0: Mandatory schema standard for machine-readable interface descriptions.
• OWASP API Security Top 10: Security documentation requirements for threat mitigation (e.g., BOLA, mass assignment).
• GDPR / CCPA / HIPAA: Data privacy boundary designations regarding PII, PHI, and financial payloads.
• RFC 7807: Standardized Problem Details for HTTP APIs across all error responses.

---

3. Prerequisites & Tool Requirements

Execution of this SOP requires explicit access provisioning and technical tooling configurations. Unauthorized documentation modifications without these prerequisites will be rejected by the CI/CD pipeline gatekeepers.

3.1 Software & Access Requirements

• Version Control: Enterprise GitHub Enterprise Server (write access to api-specifications repository).
• Authoring & Linting Suites: Redocly CLI, Spectral (custom ruleset configured via .spectral.yaml), and VS Code with the OpenAPI (Swagger) Editor extension.
• API Gateway & Testing: Postman Enterprise Workspace or Bruno, connected to enterprise Mock Server environments.
• Documentation Portal: ReadMe or Backstage Developer Portal administrator credentials.

3.2 Required Certifications & Training

• Internal API Governance & Security Certification (Course ID: SEC-API-101).
• OpenAPI 3.1 Authoring Standards Proficiency.

---

4. Roles & Responsibilities (RACI Matrix Table)

Legend:

• R = Responsible (The role that performs the activity)
• A = Accountable (The sole decision-maker; final sign-off)
• C = Consulted (Subject matter experts providing critical input)
• I = Informed (Roles updated on status milestones)

---

5. Step-by-Step Operational Procedure

Phase 1: Initialization and Spec Templating

• 1.1 Clone the master API repository (git clone git@github.com:enterprise/api-specifications.git).
• 1.2 Create a dedicated feature branch using the naming convention feature/api-[service-name]-[version].
• 1.3 Instantiate the base API specification file using the mandatory enterprise template (templates/openapi-v3.1-template.yaml).
• 1.4 Populate the info object with accurate metadata, including title, version, contact details, and terms of service URI.
• 1.5 Declare the base servers array covering production, staging, and mock environments.

Phase 2: Schema Definition & Security Scoping

• 2.1 Define all resource paths adhering to kebab-case routing standards (e.g., /v1/user-accounts/{account-id}).
• 2.2 Map all HTTP methods (GET, POST, PUT, DELETE, PATCH) with explicit summary and operationId fields.
• 2.3 Construct robust request and response schemas using JSON Schema Draft 2020-12 compliance.
• 2.4 Apply strict typing to all parameters (e.g., type: string, format: uuid, enum: [...]).
• 2.5 Integrate security schemes (components.securitySchemes) specifying OAuth2 flows with granular scopes (read:users, write:users) or HMAC authentication signatures.
• 2.6 Annotate all endpoints with explicit error response mappings conforming to RFC 7807 (400, 401, 403, 404, 429, 500).

Phase 3: Validation, Linting, and Peer Review

• 3.1 Execute local Spectral linting to verify syntax and stylistic compliance (spectral lint schemas/api-spec.yaml).
• 3.2 Ensure zero warning or error outputs from the custom enterprise Spectral ruleset.
• 3.3 Run Redocly build to verify HTML generation fidelity (redocly build-docs schemas/api-spec.yaml).
• 3.4 Open a Pull Request (PR) in GitHub, ensuring the automated CI action successfully passes schema validation checks.
• 3.5 Request formal code review from the Lead Software Engineer (LSE) and Security Engineer (SEC).

Phase 4: Publishing & Portal Synchronization

• 4.1 Merge the verified PR into the main branch upon receiving explicit approvals from the APM and SEC roles.
• 4.2 Verify the automated GitHub Action successfully pushes the updated specification to the Developer Portal (ReadMe/Backstage).
• 4.3 Validate interactive "Try It" console functionality against the sandbox mock server environment.
• 4.4 Archive previous specification versions in the /archive directory per retention protocols.

---

6. Quality Assurance & Verification Criteria

Documentation updates are subject to automated and manual gating before deployment to production environments.

6.1 Audit Checklist

• Completeness: 100% of public endpoints, parameters, headers, and payloads possess descriptive markdown documentation.
• Security Integrity: All authenticated routes explicitly declare security scopes; zero unauthenticated endpoints exist without an explicit public exemption tag.
• Mock Consistency: Postman mock collections successfully parse the published OpenAPI file with 0 syntax warnings.

6.2 Tolerance Thresholds & Acceptance Benchmarks

• Linting Error Tolerance: Exactly 0 errors. Any spectral validation failure aborts the CI/CD deployment pipeline.
• Documentation Lag: Maximum tolerance of 24 hours between code-level API deployment and documentation portal sync.
• Payload Example Validation: 100% of request/response examples must validate successfully against their respective JSON schemas.

---

7. Practical Troubleshooting Scenarios

Scenario A: CI/CD Pipeline Fails Due to Spectral Linting Violations

• Symptom: GitHub Actions workflow fails during the spectral-lint step with error code ERR_SPECTRAL_RULE.
• Root Cause: Introduction of non-standard property names, missing operationId, or undefined error response structures.
• Immediate Corrective Action Protocol:
  1. Run spectral locally to isolate the failing line numbers: npx spectral lint schemas/api-spec.yaml -v.
  2. Review the violated rule identifier (e.g., oas3-operation-security-defined).
  3. Amend the YAML file to include missing required metadata or correct casing deviations.
  4. Re-run local validation, commit changes, and push to the feature branch to trigger a fresh CI build.

Scenario B: Developer Portal Renders Incorrect Request Payload Examples

• Symptom: The interactive documentation console displays outdated schema objects or omits mandatory fields.
• Root Cause: Caching lag in the developer portal synchronization layer or schema inheritance (allOf) parsing failure by Redocly.
• Immediate Corrective Action Protocol:
  1. Force a manual cache purge within the Developer Portal administration dashboard (ReadMe/Backstage).
  2. Inspect the OpenAPI file for circular references or complex allOf nesting; flatten schemas into direct properties objects where necessary.
  3. Re-trigger the portal synchronization webhook manually via the GitHub repository settings webhooks interface.

Scenario C: Postman Mock Server Returns 404 on Newly Documented Endpoints

• Symptom: API consumers report that newly published endpoint paths fail with 404 Not Found in the mock environment.
• Root Cause: Path mismatch between the OpenAPI specification file and the API Gateway routing configuration, or missing base path declarations.
• Immediate Corrective Action Protocol:
  1. Compare the servers[0].url and path strings in the OpenAPI document against the API Gateway routing table.
  2. Ensure path parameters use curly braces consistently (e.g., {id} not :id).
  3. Update the specification file, re-validate, merge to main, and verify gateway synchronization.