Api Documentation Example Swagger

Standard Operating Procedure: API Documentation Generation and Validation via OpenAPI/Swagger

1. Document Control Block

• Document ID: SOP-TR-OPS-4091
• Effective Date: October 24, 2023
• Version: 3.2.0
• Review Cadence: Semi-Annual
• Target Audience: API Developers, Technical Writers, Quality Assurance Engineers, Chief Operations Architects

2. Executive Summary & Scope

This Standard Operating Procedure (SOP) defines the mandatory protocol for authoring, validating, rendering, and maintaining RESTful API documentation using the OpenAPI Specification (OAS) 3.0+ and Swagger UI within Template Registry infrastructure. Adherence to this document ensures strict compliance with enterprise security baselines, regulatory interoperability frameworks (e.g., SOC2 Type II, ISO/IEC 27001), and developer experience (DevEx) reliability SLAs. This scope covers all production-grade microservices deployed across internal and external network boundaries.

3. Prerequisites & Tool Requirements

• Software Dependencies: Node.js (v18.x LTS+), Spectral CLI (@stoplight/spectral-cli), Docker Engine (v24.x+).
• Access & Permissions: Write access to the central template-registry-specs repository; API Gateway administrative clearance.
• Standards & Specifications: OpenAPI 3.0.3 specification familiarity; Template Registry REST API Design Guidelines (TR-RDG-09).
• Safety & Compliance: Zero-trust credential handling protocols (no hardcoded API keys, tokens, or PII in specification files).

4. Roles & Responsibilities (RACI Matrix Table)

5. Step-by-Step Operational Procedure

Phase 1: Specification Authoring & Structuring

• Initialize or update the target service directory within the OpenAPI repository structure (/specs/v1/[service-name]/openapi.yaml).
• Define the root metadata block including openapi: 3.0.3, info.title, info.version (Semantic Versioning), and info.description.
• Configure global servers objects mapping explicitly to sandbox, staging, and production routing endpoints.
• Implement strict JSON Schema typing for all request bodies, query parameters, and response payloads using explicit type, format, and example attributes.

Phase 2: Security & Authentication Modeling

• Declare security schemes in the components/securitySchemes block (e.g., OAuth2 with Authorization Code flow or mutual TLS).
• Apply appropriate security requirements globally or granularly at the path operation level (security: array).
• Verify that no production secrets, internal IP addresses, or proprietary tokens are present in examples or descriptions.

Phase 3: Automated Linter & Schema Validation

• Execute local Spectral linting against the enterprise ruleset:

  spectral lint specs/v1/[service-name]/openapi.yaml --ruleset .spectral.yaml
  

• Resolve all reported error and warning diagnostics prior to moving to integration.
• Execute programmatic schema validation using the Docker-based OpenAPI generator:

  docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli validate -i /local/specs/v1/[service-name]/openapi.yaml
  

Phase 4: Swagger UI Rendering & Verification

• Spin up the local development container for Swagger UI to verify visual rendering:

  docker run -p 8080:8080 -e SWAGGER_JSON=/specs/openapi.yaml -v ${PWD}/specs/v1/[service-name]:/specs swaggerapi/swagger-ui
  

• Navigate to http://localhost:8080 to manually verify interactive "Try it out" execution paths, schema displays, and markdown rendering.
• Ensure all status codes (200, 201, 400, 401, 403, 404, 500) map explicitly to documented schema payloads.

Phase 5: CI/CD Pipeline Integration & Publishing

• Commit changes to a dedicated feature branch and open a Pull Request (PR) against the main specification registry.
• Verify that automated GitHub Actions / GitLab CI pipelines successfully pass all linting, breaking-change detection, and schema compilation steps.
• Merge the PR upon receiving documented sign-off from the Technical Writer and automated quality gates, triggering automatic publishing to the Developer Portal.

6. Quality Assurance & Verification Criteria

• Audit Checklist:
  • 100% of public endpoints documented with operational summaries and descriptions.
  • Zero Spectral linter errors or unhandled warnings.
  • Complete request/response example coverage for all HTTP 2xx and 4xx responses.
• Tolerance Thresholds: Maximum allowable schema drift between actual code implementation and OpenAPI specification is 0%. API contracts must be updated prior to code merges under contract-first development rules.
• Acceptance Benchmark: Successful execution of end-to-end mock server tests generated directly from the finalized Swagger specification.

7. Practical Troubleshooting Scenarios

Scenario A: Spectral Linter Fails on Undefined Component References ($ref)

• Symptom: CLI returns oas3-valid-media-example or $ref pointer not found during local validation.
• Immediate Corrective Action Protocol:
  1. Inspect the relative file path or internal anchor within the $ref string (e.g., #/components/schemas/ErrorResponse).
  2. Verify that the target schema exists inside the components dictionary of the active file or modularized external specification file.
  3. Ensure YAML indentation adheres strictly to 2-space standards and contains no tab characters.
  4. Re-run Spectral to confirm resolution before pushing commits.

Scenario B: Swagger UI Fails to Render Request Body Examples

• Symptom: Interactive UI displays "No Spec" or fails to populate default input parameters in the "Try it out" panel.
• Immediate Corrective Action Protocol:
  1. Confirm that content type declarations explicitly match consuming headers (e.g., application/json).
  2. Validate that the example or examples block resides directly underneath the media type object, not the schema root object.
  3. Run the OpenAPI validation CLI container locally to catch structural typing mismatches that bypass basic YAML parsers.