feat(openapi): add bearerAuth description + apiKeyAuth alias + schema descriptions#3781
Conversation
… descriptions - Unquote type/scheme/bearerFormat (YAML canonical form) - Add description to bearerAuth security scheme - Add apiKeyAuth as legacy-alias security scheme (points to bearerAuth) - Add description to SuccessResponse and ErrorResponse schema components - 6 new unit tests covering all additions Closes #3780. References infra#38 (T13 Fix B sub-step).
|
Warning Review limit reached
More reviews will be available in 13 minutes and 48 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3781 +/- ##
=======================================
Coverage 90.19% 90.19%
=======================================
Files 152 152
Lines 5020 5020
Branches 1598 1598
=======================================
Hits 4528 4528
Misses 387 387
Partials 105 105
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Sentry.
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR improves the devkit’s baseline OpenAPI spec by enriching security scheme and schema component descriptions, and adds unit tests intended to guard these baseline expectations in the generated merged spec.
Changes:
- Enhanced
bearerAuthsecurity scheme with a human-readable description and normalized YAML scalar formatting. - Added
apiKeyAuthas a legacy-named security scheme intended to aliasbearerAuth. - Added descriptions to
SuccessResponseandErrorResponseschema components, plus new unit tests asserting these fields are present in the served spec.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| modules/core/doc/index.yml | Updates baseline OpenAPI components: security schemes + schema descriptions. |
| lib/services/tests/express.docs.unit.tests.js | Adds unit tests asserting the merged spec contains the new baseline descriptions/schemes. |
| apiKeyAuth: | ||
| type: http | ||
| scheme: bearer | ||
| description: | | ||
| Legacy alias for `bearerAuth`. New integrations should use `bearerAuth`. |
| schemas: | ||
| SuccessResponse: | ||
| type: object | ||
| description: Standard success envelope. data type varies by endpoint. |
| beforeEach(() => { | ||
| jest.resetModules(); | ||
| jest.unstable_mockModule('fs', () => ({ | ||
| default: { readFileSync: jest.fn().mockReturnValue('mocked') }, | ||
| readFileSync: jest.fn().mockReturnValue('mocked'), | ||
| })); | ||
| jest.unstable_mockModule('js-yaml', () => ({ | ||
| default: { load: jest.fn().mockReturnValue(mockCoreYamlDoc) }, | ||
| load: jest.fn().mockReturnValue(mockCoreYamlDoc), | ||
| })); |
| const buildMockApp = () => { | ||
| const routes = {}; | ||
| return { get: (path, handler) => { routes[path] = handler; }, _routes: routes }; | ||
| }; | ||
|
|
||
| const callSpecRoute = (app) => { | ||
| const handler = app._routes['/api/spec.json']; | ||
| if (!handler) throw new Error('/api/spec.json route not registered'); | ||
| let spec = null; | ||
| const res = { json: (body) => { spec = body; } }; | ||
| handler({}, res); | ||
| return spec; | ||
| }; |
Summary
Improves the devkit OpenAPI baseline in
modules/core/doc/index.yml:type,scheme,bearerFormatvalues (YAML canonical form — quoted strings → unquoted)descriptiontobearerAuthsecurity scheme (generic: explains Authorization: Bearer header pattern)apiKeyAuthsecurity scheme as a legacy alias forbearerAuth(description: "Legacy alias forbearerAuth. New integrations should usebearerAuth.")descriptiontoSuccessResponseschema componentdescriptiontoErrorResponseschema componentWhy
These are generic improvements that belong in devkit, not in downstream
modules/core/doc/index.ymloverrides. TheapiKeyAuthalias allows downstreams (e.g. Trawl) that referenceapiKeyAuthin route security declarations to work correctly without patching every route annotation. Descriptions make the generated Redoc docs self-explanatory.Part of T13 Fix B sub-step (infra#38 no-ledger drift cleanup). After this PR merges, the trawl_node side (Fix C) will:
/update-stackmodules/core/doc/index.ymlto the devkit baselinetags+x-tagGroupsto per-module doc filesTest coverage
6 new unit tests in
lib/services/tests/express.docs.unit.tests.js:bearerAuthsecurity scheme exists in merged specbearerAuthhas a description fieldapiKeyAuthsecurity scheme exists as legacy aliasapiKeyAuthdescription mentionsbearerAuthas canonicalSuccessResponseschema has a descriptionErrorResponseschema has a descriptionAll 17 tests in the file pass (6 new + 11 existing). Lint clean.
References