Api Doc Template

Standard Operating Procedure: api doc template

Document ID: SOP-OPS-ENT-8842
Compliance Domain: Enterprise API Lifecycle Management & Technical Governance

---

1. Document Control & Revision History

---

2. Executive Summary & Scope

2.1 Purpose

This Standard Operating Procedure (SOP) defines the mandatory operational framework for authoring, reviewing, publishing, and maintaining Application Programming Interface (API) documentation across all enterprise software systems. Adherence ensures absolute consistency, security compliance, machine-readability, and seamless developer onboarding.

2.2 Operational Boundaries

This SOP applies to all internal, partner-facing, and public-facing APIs developed, maintained, or integrated by enterprise engineering squads, third-party contractors, and acquired entities.

2.3 Regulatory & Standards Compliance

All API documentation produced under this SOP must conform to the following standards:

• OpenAPI Specification (OAS) Version 3.1.0: Mandatory structural standard for machine-readable interface descriptions.
• RFC 7807: Problem Details for HTTP APIs (mandatory error-payload schema).
• OWASP API Security Top 10: Mandatory risk mitigation documentation.
• ISO/IEC/IEEE 26514: Requirements for designers and developers of user documentation.

---

3. Prerequisites & Tool Requirements

Engineers and technical writers must secure the following permissions, software toolchains, and credentials before initiating API documentation workflows:

• Access & Permissions:
  • Enterprise Git Repository access (Write access to the designated service repository).
  • Developer Portal CMS (e.g., Backstage, ReadMe, or Redocly) administrative or contributor role.
  • Postman Enterprise Workspace or equivalent API client testing seat.
• Software & Toolchain Requirements:
  • Git (v2.30 or higher) with SSH key authentication configured.
  • Visual Studio Code or equivalent IDE with YAML/JSON language servers and Redocly CLI installed (npm i -g @redocly/cli).
  • Spectral Linter (@stoplight/spectral-cli) for OAS constraint validation.
  • Docker Engine (v20.10+) for local documentation preview containerization.
• Certifications & Training:
  • Completion of Enterprise Secure Coding & API Governance module (Internal LMS Course ID: SEC-801).

---

4. Roles & Responsibilities (RACI Matrix Table)

(Legend: Responsible – executes the work; Accountable – ultimate owner; Consulted – provides input; Informed – kept updated)

---

5. Step-by-Step Operational Procedure

Phase 1: Schema-First Design & Initialization

• 1.1 Create the API specification file adhering to OpenAPI 3.1.0 standards (openapi.yaml or openapi.json) within the service source repository under /docs/api/.
• 1.2 Populate mandatory metadata fields: info.title, info.version, info.description, and info.contact (including enterprise support email).
• 1.3 Define the base server URLs (servers object) explicitly separating sandbox, staging, and production environments.

Phase 2: Component & Endpoint Documentation

• 2.1 Document all HTTP methods (GET, POST, PUT, PATCH, DELETE) with concise summary and comprehensive description blocks.
• 2.2 Map all path, query, and header parameters, explicitly detailing data types, constraints (pattern, minimum, maximum), and mandatory/optional status.
• 2.3 Implement request bodies utilizing explicit JSON schemas (application/json), avoiding generic object types without defined properties.
• 2.4 Document all standard HTTP status codes (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error).
• 2.5 Ensure error payloads strictly implement the RFC 7807 (application/problem+json) schema format.

Phase 3: Security & Authentication Specification

• 3.1 Define security schemes (components.securitySchemes) explicitly declaring support for OAuth 2.0 (with authorization URL and token URL) or Mutual TLS (mTLS) / API Keys.
• 3.2 Apply global or endpoint-specific security requirements (security object) across all protected routes.
• 3.3 Explicitly document rate-limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) in the response headers section.

Phase 4: Linting, Validation, & Peer Review

• 4.1 Execute local Spectral linting to verify compliance with enterprise API style guides: spectral lint docs/api/openapi.yaml.
• 4.2 Execute Redocly CLI build check to ensure HTML generation succeeds without warnings: redocly build-docs docs/api/openapi.yaml.
• 4.3 Open a Pull Request (PR) against the main branch, assigning the Tech Lead and Technical Writer as primary reviewers.

Phase 5: Publishing & Portal Synchronization

• 5.1 Merge the validated PR into the main branch following successful CI/CD pipeline execution.
• 5.2 Verify that the CI/CD pipeline automatically syncs the updated specification to the Enterprise Developer Portal.
• 5.3 Conduct a live test of at least one core request via the Developer Portal's "Try It Out" interactive console.

---

6. Quality Assurance & Verification Criteria

Documentation deployments must meet the following automated and manual quality gates before release sign-off:

• Spectral Linter Benchmark: Zero errors and zero warnings against the enterprise ruleset (.spectral.yaml).
• Schema Completeness Threshold: 100% of endpoints must feature:
  • At least one successful response example (200 or 201).
  • At least two error response examples (400 and 500).
  • Complete descriptions for every property within request and response schemas.
• Security Validation: SecOps sign-off required if authentication scopes or security schemes are modified.

---

7. Practical Troubleshooting Scenarios

Scenario A: CI/CD Pipeline Fails on Spectral Linting (ERR_SPEC_MISSING_PROPERTY)

• Symptom: The automated build pipeline rejects the commit with an error stating a path operation lacks a required description or response definition.
• Immediate Corrective Action Protocol:
  1. Run npx @stoplight/spectral-cli lint docs/api/openapi.yaml locally to isolate the exact line number.
  2. Open the openapi.yaml file and locate the offending path/operation.
  3. Add the missing description or response object matching RFC 7807 guidelines.
  4. Re-run the linter locally, commit the fix, and force-push to update the Pull Request.

Scenario B: Interactive "Try It Out" Console Fails with CORS Error

• Symptom: Developers utilizing the Developer Portal console experience browser-level CORS (Cross-Origin Resource Sharing) blocks when hitting staging APIs.
• Immediate Corrective Action Protocol:
  1. Verify that the API Gateway / API Management (APIM) layer includes the Developer Portal domain in its Access-Control-Allow-Origin policy.
  2. Ensure preflight OPTIONS requests are correctly handled by the target microservice route.
  3. Escalate to the Infrastructure/SecOps team to update the API Gateway inbound CORS policy if the issue persists across all endpoints.

Scenario C: Broken Request/Response Examples in Published Portal

• Symptom: Code snippets generated in the Developer Portal display invalid JSON syntax or mismatched data types relative to the schema definition.
• Immediate Corrective Action Protocol:
  1. Locate the example definitions (example: or examples:) under the respective schema component in openapi.yaml.
  2. Validate all JSON/YAML example strings using a strict syntax validator (e.g., jq . or an internal JSON linter).
  3. Ensure data types within examples strictly match defined types (e.g., strings enclosed in quotes, integers without quotes).
  4. Push the corrected schema to trigger a manual documentation rebuild in the CMS.