Architecture Note: OpenAPI as a Versioned CI-Gated Contract

Problem: Teams often ship API implementations without a contract that is reviewed, validated, and versioned like code. Consumers hit undocumented endpoints, breaking changes land in production silently, and Swagger UI--meant to help--can expose internal routes or leak configuration when left unguarded. The result is a drift between what the code serves and what consumers rely on, and every new release becomes a game of telephone.

Takeaway: Treat the OpenAPI document as a first-class release artifact: keep it in the service repository, validate it in CI, version it alongside implementation, and enforce all authentication and authorization at the gateway--not in the UI.

Requirements: one reviewable source of truth

The OpenAPI document becomes the single point of reference for design reviews, code generation, and client SDK production. Because the document is untrusted input to tooling, every field--from server URLs to example values--must be production-safe and free of secrets.

Smallest suitable design

Keep openapi.yaml or openapi.json in the service repository, validate it in CI, and build a static Swagger UI bundle during deployment. Publish one spec per service and per audience rather than one global spec. This keeps the contract surface area small, makes diffing feasible, and aligns the spec lifecycle with the service release cycle.

# Example: minimal openapi.yaml snippet
openapi: 3.0.3
info:
  title: Example Service API
  version: 1.0.0
paths: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Trust and data boundaries

The OpenAPI document is untrusted input to code generators and UI tooling. Examples and server URLs must be non-secret. The securitySchemes object documents authentication schemes but does not enforce them; the API gateway or service runtime must enforce authn, authz, quotas, and tenancy. Placing bearer tokens, internal hostnames, or customer data into examples or server fields is a direct violation of this boundary.

Operational checks that matter

CI should run an OpenAPI linter and fail on unresolved references, missing operationIds, invalid security requirements, or schema drift from the implementation. A diff step against the previous release classifies changes as non-breaking, potentially breaking, or breaking before merge. Smoke tests load Swagger UI from a clean browser profile against staging; protected operations must return 401 or 403 without valid credentials. Additionally, check CSP and CORS headers for UI assets, and confirm the spec endpoint's cache lifetime is shorter than the deployment rollback window.

# Typical CI command (run in CI job with read access to repository)
npx @redocly/cli lint ${SPEC_PATH}
# Expected check: exit code 0 if no lint errors
# Relevant risk: false positives from overly strict rules; tune ruleset to avoid blocking legitimate changes

Failure modes and diagnostic pointers

• Implementation drift: the code adds or changes endpoints without a corresponding spec update.
• OpenAPI 3.0 vs 3.1 mismatch: nullable handling, type arrays, and webhooks differ between versions. Pin one version and use matching validators and codegen.
• Public UI exposure: if server variables are not stripped, Swagger UI can reveal internal endpoints.
• CSRF in browser Authorize flows: access tokens stored in localStorage are vulnerable to cross-site request forgery.
• UI performance: very large specs--over a few hundred paths--make the UI sluggish and increase CI validation time.

OpenAPI 3.0 vs 3.1: key differences

Aspect	OpenAPI 3.0	OpenAPI 3.1
Nullable fields	nullable: true on schema objects	Use type: [string, null] or nullable: true with transitional support
Type arrays	Not supported; use oneOf or anyOf	First-class support for [string, null] type arrays
Webhooks	Experimental keyword, limited tooling support	Native webhooks field, full HTTP method and auth support

Conditions that would change this design

When multiple consumer languages or generated SDKs are required, stricter semver and contract tests become mandatory. Partner-facing APIs need versioned specs, deprecation windows, OAuth scope restrictions, and signed or registry-managed artifacts. High change rates favor a spec-first development flow with generated stubs, but only if the team can maintain the discipline to keep the contract in sync.

Rollback as a release artifact discipline

Treat the published OpenAPI document as a release artifact with a version number and checksum. If a bad spec ships, roll back both the implementation and the published document together so clients do not validate against a contract the service no longer serves. Tag the spec version at the same git commit as the service version; CI pipelines should reject a spec change that is not paired with an implementation change.

Limitations and practical verification

CI linters catch many errors but may not resolve all external references or detect semantic drift. The most reliable verification is a staged smoke test: load Swagger UI from a fresh browser profile, attempt a protected operation without a token, and confirm a 401/403 response. For OpenAPI 3.1, validate the spec against JSON Schema 2020-12 semantics; for 3.0, confirm nullable and example behavior with the exact codegen toolchain your clients use. Keep a checklist of these checks and treat any failure as a blocker before merge.