feat(car-sharing): authz-aware OpenAPI generation

[intech]

What

Adds OpenAPI v3.1 generation to the car-sharing example so the published contract reflects Connectum's proto authz — the same options createProtoAuthzInterceptor enforces at runtime also drive the spec, so the two cannot drift.

How

Two decoupled steps, run via pnpm openapi:

1. Base spec — buf.gen.openapi.yaml (separate from the offline buf.gen.yaml) runs the sudorandom/protoc-gen-connect-openapi buf remote plugin → OpenAPI v3.1 under openapi/. Isolated so the network plugin never runs during buf:generate/tests.
2. Authz overlay — scripts/openapi-authz.ts reads connectum.auth.v1 options via resolveMethodAuth (the same reader the runtime interceptor uses) and injects per-operation security (bearerAuth), security: [] + x-connectum-public for public methods, and x-connectum-required-roles/-scopes.

Verified

• TripService (4 methods): StartTrip/GetTrip → bearerAuth (secured); EndTrip/RecordTrip → security: [] + x-connectum-public (tokenless worker RPCs). Confirmed against the generated openapi/trips/v1/trips.openapi.yaml paths.
• FleetService.ListVehicles is server-streaming → no operation in the base spec (overlay skips it); fleet/billing are public.
• pnpm typecheck ✓ · pnpm test 39/39 ✓
• Works on the published @connectum/auth 1.0.0 (the ./proto subpath export). No published-package change.

Design rationale: ADR-030; usage: the OpenAPI guide (docs PR).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Published OpenAPI 3.1 specifications for Billing, Fleet, and Trips services with complete HTTP endpoint definitions, request/response schemas, error handling details, and JWT authentication requirements
  • Automated authorization metadata injection into OpenAPI specifications

• Documentation

  • Added detailed OpenAPI generation and regeneration process documentation with configuration and usage instructions

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c0da8c8d-ec65-4531-9eaa-83422342b200

📥 Commits

Reviewing files that changed from the base of the PR and between addad23 and 3a6d20e.

📒 Files selected for processing (7)

• car-sharing/README.md
• car-sharing/buf.gen.openapi.yaml
• car-sharing/openapi/billing/v1/billing.openapi.yaml
• car-sharing/openapi/fleet/v1/fleet.openapi.yaml
• car-sharing/openapi/trips/v1/trips.openapi.yaml
• car-sharing/package.json
• car-sharing/scripts/openapi-authz.ts

---

📝 Walkthrough

Walkthrough

Adds a two-step OpenAPI generation pipeline to the car-sharing example. A new buf.gen.openapi.yaml config generates base specs from proto using the sudorandom-connect-openapi plugin. A new scripts/openapi-authz.ts script then overlays JWT bearer security and x-connectum-* extensions per operation via resolveMethodAuth. Three generated OpenAPI 3.1.0 specs are committed for Billing, Fleet, and Trips services. A README section documents the pipeline.

Changes

OpenAPI Generation Pipeline

Layer / File(s)	Summary
Generation tooling: buf config and npm script car-sharing/buf.gen.openapi.yaml, car-sharing/package.json	Adds buf.gen.openapi.yaml for base spec generation via the sudorandom-connect-openapi plugin, wires a new openapi npm script chaining buf and the overlay script, and adds yaml as a devDependency.
Authz overlay script car-sharing/scripts/openapi-authz.ts	Parses each service's generated YAML, injects a bearerAuth security scheme, iterates methods via resolveMethodAuth to set per-operation security arrays and x-connectum-* extensions (public flag, required roles/scopes), writes updated specs, and deletes the generated openapi/connectum noise spec.
Generated OpenAPI contracts car-sharing/openapi/billing/v1/billing.openapi.yaml, car-sharing/openapi/fleet/v1/fleet.openapi.yaml, car-sharing/openapi/trips/v1/trips.openapi.yaml	Three OpenAPI 3.1.0 specs for Billing (5 POST ops), Fleet (3 POST ops + 1 stub), and Trips (4 POST ops), each with Connect header parameters, domain request/response schemas, a shared connect.error model, bearerAuth security scheme, and per-operation security entries reflecting proto authz options.
README documentation car-sharing/README.md	Adds a section describing the two-step generation flow, per-operation security injection behavior, streaming RPC omission, and the pending x-internal handling for internal proto methods.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

type:feature

Poem

🐇 Hop, hop, a spec appears,
From proto fields to YAML frontiers!
Bearer tokens, roles, and scopes in view,
The OpenAPI contract shines brand new.
Public paths wave with an empty array,
While internal hops stay locked away. 🔐

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/car-sharing-openapi

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}