ci(openapi): validate contract in CI

Author: AlisinaDevelo

.github/workflows/ci.yml

@@ -34,6 +34,9 @@ jobs:
       - name: Lint
         run: npm run lint
 
+      - name: OpenAPI contract
+        run: npm run contract
+
       - name: Test
         run: npm test
 

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Deterministic `npm run benchmark:local` benchmark for cold upstream-backed searches and warm cache hits.
 - Cache resilience for article searches: cache read/write failures are logged and metriced without failing requests.
 - In-flight coalescing for identical cache misses so concurrent same-key searches share one upstream request per process.
+- Redocly-powered `npm run contract` check for the OpenAPI document, wired into CI.
 
 ### Security
 

README.md

@@ -122,6 +122,7 @@ Errors: `{ "error": "message" }`. Rate limit: `429` with standard rate-limit hea
 | `npm run test:watch` | Vitest watch. |
 | `npm run test:coverage` | Tests + coverage. |
 | `npm run lint` | ESLint. |
+| `npm run contract` | Validate `docs/openapi.yaml` with Redocly CLI. |
 | `npm run smoke` | Curl-based smoke test against a running instance (`BASE_URL`, `QUERY`, `COUNT`, optional `CLIENT_API_KEY`). |
 | `npm run benchmark:local` | Builds the app, starts a fake GNews provider, and measures cold searches vs warm cache hits. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md). |
 

docs/CI.md

@@ -9,26 +9,27 @@ The [workflow](../.github/workflows/ci.yml) runs on `ubuntu-latest` with **Node.
 1. **`npm ci`** — reproducible install from `package-lock.json`.
 2. **`npm audit --audit-level=high`** — fails the job if high or critical advisories remain.
 3. **`npm run lint`** — [ESLint](https://eslint.org/) on `src/`, `test/`, and `vitest.config.ts`.
-4. **`npm test`** — [Vitest](https://vitest.dev/). GNews is **not** called: tests mock `axios`; no API key in GitHub Actions.
-5. **`npm run test:coverage`** — **Node 22 only**; uploads the `coverage/` directory (including `lcov.info`) as a workflow artifact named `coverage-lcov`.
-6. **[Codecov](https://codecov.io)** — **Node 22 only**; uploads `coverage/lcov.info`. For private repos set repository secret `CODECOV_TOKEN`. `fail_ci_if_error` is off so missing token does not break the build.
-7. **`npm run build`** — TypeScript compile to `dist/`.
+4. **`npm run contract`** — [Redocly CLI](https://redocly.com/docs/cli) validates `docs/openapi.yaml` so the published API contract stays parseable and policy-compliant.
+5. **`npm test`** — [Vitest](https://vitest.dev/). GNews is **not** called: tests mock `axios`; no API key in GitHub Actions.
+6. **`npm run test:coverage`** — **Node 22 only**; uploads the `coverage/` directory (including `lcov.info`) as a workflow artifact named `coverage-lcov`.
+7. **[Codecov](https://codecov.io)** — **Node 22 only**; uploads `coverage/lcov.info`. For private repos set repository secret `CODECOV_TOKEN`. `fail_ci_if_error` is off so missing token does not break the build.
+8. **`npm run build`** — TypeScript compile to `dist/`.
 
 ### Container (`docker` job)
 
-8. **Buildx build** — [Dockerfile](../Dockerfile) with **`provenance: mode=max`** and **SBOM** (no registry push). Validates supply-chain metadata generation in CI.
+9. **Buildx build** — [Dockerfile](../Dockerfile) with **`provenance: mode=max`** and **SBOM** (no registry push). Validates supply-chain metadata generation in CI.
 
 ### Pull requests only
 
-9. **[Dependency review](../.github/workflows/dependency-review.yml)** — flags vulnerable or blocked dependencies introduced by the PR.
+10. **[Dependency review](../.github/workflows/dependency-review.yml)** — flags vulnerable or blocked dependencies introduced by the PR.
 
 ### Every push / PR (supply chain)
 
-10. **[SBOM](../.github/workflows/supply-chain.yml)** — [Anchore SBOM Action](https://github.com/anchore/sbom-action) produces SPDX JSON and uploads it as a workflow artifact.
+11. **[SBOM](../.github/workflows/supply-chain.yml)** — [Anchore SBOM Action](https://github.com/anchore/sbom-action) produces SPDX JSON and uploads it as a workflow artifact.
 
 ### `main` branch pushes only
 
-11. **[Provenance](../.github/workflows/provenance.yml)** — [build provenance attestation](https://github.com/actions/attest-build-provenance) for `package-lock.json` (best-effort; `continue-on-error` if attestations are unavailable on the plan).
+12. **[Provenance](../.github/workflows/provenance.yml)** — [build provenance attestation](https://github.com/actions/attest-build-provenance) for `package-lock.json` (best-effort; `continue-on-error` if attestations are unavailable on the plan).
 
 ### Code scanning (`CodeQL` workflow)
 
@@ -48,6 +49,7 @@ When you push an annotated tag matching `v*.*.*`, [release.yml](../.github/workf
 npm ci
 npm audit --audit-level=high
 npm run lint
+npm run contract
 npm test
 npm run build
 docker build .

docs/openapi.yaml

@@ -5,6 +5,9 @@ info:
     REST API backed by the GNews search endpoint.
     When `CLIENT_API_KEYS` is set on the server, send a matching `X-API-Key` header on `/api/*` requests.
   version: 1.2.0
+  license:
+    name: MIT
+    url: https://opensource.org/license/mit
 servers:
   - url: http://localhost:3000
     description: Local development
@@ -14,6 +17,7 @@ paths:
     get:
       summary: Liveness probe
       operationId: getHealth
+      security: []
       responses:
         "200":
           description: Process is running
@@ -27,6 +31,7 @@ paths:
       summary: Readiness probe
       description: Returns 503 when `GNEWS_API_KEY` is not configured (non-test environments).
       operationId: getReady
+      security: []
       responses:
         "200":
           description: Ready to serve traffic
@@ -45,6 +50,7 @@ paths:
     get:
       summary: Prometheus metrics
       operationId: getMetrics
+      security: []
       responses:
         "200":
           description: Prometheus text / OpenMetrics exposition format
@@ -53,10 +59,26 @@ paths:
               schema:
                 type: string
 
+  /openapi.yaml:
+    get:
+      summary: OpenAPI contract
+      operationId: getOpenApiYaml
+      security: []
+      responses:
+        "200":
+          description: OpenAPI 3 document
+          content:
+            application/yaml:
+              schema:
+                type: string
+
   /api/articles:
     get:
       summary: Search articles
       operationId: searchArticles
+      security:
+        - ApiKeyAuth: []
+        - {}
       parameters:
         - name: X-API-Key
           in: header
@@ -136,6 +158,9 @@ paths:
     get:
       summary: Find article by exact title
       operationId: getArticleByTitle
+      security:
+        - ApiKeyAuth: []
+        - {}
       parameters:
         - name: X-API-Key
           in: header
@@ -174,6 +199,9 @@ paths:
     get:
       summary: Filter articles by news source name
       operationId: listArticlesBySource
+      security:
+        - ApiKeyAuth: []
+        - {}
       parameters:
         - name: X-API-Key
           in: header
@@ -250,6 +278,13 @@ paths:
           $ref: "#/components/responses/InternalError"
 
 components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: Required for `/api/*` requests only when the server sets `CLIENT_API_KEYS`.
+
   responses:
     Unauthorized:
       description: Missing or invalid X-API-Key when CLIENT_API_KEYS is configured

package-lock.json

@@ -14,6 +14,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src test vitest.config.ts",
+    "contract": "redocly lint docs/openapi.yaml",
     "smoke": "sh scripts/smoke-test.sh",
     "benchmark:local": "npm run build && node scripts/local-benchmark.mjs"
   },
@@ -44,6 +45,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@redocly/cli": "^2.34.0",
     "@types/express": "^4.17.21",
     "@types/express-rate-limit": "^5.1.3",
     "@types/node": "^20.19.43",

package.json

@@ -0,0 +1,6 @@
+extends:
+  - recommended
+
+rules:
+  no-server-example.com: off
+  operation-4xx-response: off