feat(openapi): support UndefinedError in commonSchemas for spec generation#655
Conversation
…ation `UndefinedError` is used for undefined errors, which is very useful when using Type-Safe Error Handling.
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
dosubot
Bot
added
the
size:L
WalkthroughA new Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant PlaygroundApp
participant OpenAPIGenerator
participant OpenAPIDocument
User->>PlaygroundApp: Configure OpenAPI with commonSchemas (including UndefinedError)
PlaygroundApp->>OpenAPIGenerator: Generate OpenAPI spec
OpenAPIGenerator->>OpenAPIDocument: Add UndefinedError schema to components
OpenAPIGenerator->>OpenAPIDocument: Reference UndefinedError in error responses
OpenAPIDocument-->>User: Returns OpenAPI spec with centralized error schema
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
⏰ Context from checks skipped due to timeout of 90000ms (2)
✨ Finishing Touches
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @unnoq, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request enhances the OpenAPI generator by allowing the standard UndefinedError schema, commonly used in type-safe error handling, to be defined and referenced via the commonSchemas configuration. This results in a cleaner and more maintainable generated OpenAPI specification by leveraging schema components and references.
Highlights
- Feature: UndefinedError in commonSchemas: Added support for defining the standard
UndefinedErrorschema within thecommonSchemasoption of the OpenAPI generator. This allows users to register theUndefinedErrorschema once and have it referenced throughout the generated spec, improving readability and reducing duplication. - OpenAPI Spec Generation: Modified the internal logic to resolve the
UndefinedErrorschema fromcommonSchemasand use a$refto it in the generated error responses for procedures, replacing the previous approach of inlining the schema. - Documentation Update: Updated the OpenAPI specification documentation to include an example of how to add
UndefinedErrorto thecommonSchemasconfiguration. - Test Coverage: Added a new test case specifically for defining
UndefinedErrorincommonSchemasand updated existing tests to verify that the generated spec correctly uses a$refwhenUndefinedErroris defined this way.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configureGemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
The code changes introduce support for UndefinedError in common schemas for OpenAPI specification generation. This allows for better handling of undefined errors, especially when using type-safe error handling. The changes include modifications to the OpenAPI generator to process and include the UndefinedError schema in the generated specification, as well as updates to tests and playground examples to reflect this new functionality.
| - The `strategy` option determines which schema definition to use when input and output types differ (defaults to `input`). This is needed because we cannot use the same `$ref` for both input and output in this case. | ||
|
|
||
| - `UndefinedError` is used for undefined errors, which is very useful when using [Type-Safe Error Handling](/docs/error-handling#type‐safe-error-handling) |
There was a problem hiding this comment.
It would be helpful to include a brief description of what UndefinedError represents in the context of the OpenAPI specification.
| - The `strategy` option determines which schema definition to use when input and output types differ (defaults to `input`). This is needed because we cannot use the same `$ref` for both input and output in this case. | |
| - `UndefinedError` is used for undefined errors, which is very useful when using [Type-Safe Error Handling](/docs/error-handling#type‐safe-error-handling) | |
| - `UndefinedError` is used for undefined errors, which indicates a fallback error schema when specific error types are not defined. It is very useful when using [Type-Safe Error Handling](/docs/error-handling#type‐safe-error-handling) |
Codecov ReportAll modified and coverable lines are covered by tests ✅ 📢 Thoughts on this report? Let us know! |
More templates
@orpc/arktype
@orpc/client
@orpc/contract
@orpc/hey-api
@orpc/nest
@orpc/openapi
@orpc/openapi-client
@orpc/react
@orpc/react-query
@orpc/server
@orpc/shared
@orpc/solid-query
@orpc/standard-server
@orpc/standard-server-aws-lambda
@orpc/standard-server-fetch
@orpc/standard-server-node
@orpc/standard-server-peer
@orpc/svelte-query
@orpc/tanstack-query
@orpc/valibot
@orpc/vue-colada
@orpc/vue-query
@orpc/zod
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (6)
playgrounds/next/src/app/api/[[...rest]]/route.ts (1)
28-37: Same comment as in Contract-First playgroundSee earlier note about validating generator support and deduplicating the
commonSchemasdefinition.playgrounds/astro/src/pages/api/[...rest].ts (1)
29-38: Same comment as in Contract-First playgroundSee earlier note about validating generator support and deduplicating the
commonSchemasdefinition.playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts (1)
29-38: Same comment as in Contract-First playgroundSee earlier note about validating generator support and deduplicating the
commonSchemasdefinition.playgrounds/nuxt/server/routes/api/[...].ts (1)
27-36: Same comment as in Contract-First playgroundSee earlier note about validating generator support and deduplicating the
commonSchemasdefinition.playgrounds/nest/src/reference/reference.service.ts (1)
38-38: Same remark as in tanstack-start.
See previous comment about defining a shared constant to avoid string-literal drift.playgrounds/solid-start/src/routes/api/[...rest].ts (1)
37-37: Same remark as in tanstack-start.
See previous comment about defining a shared constant to avoid string-literal drift.
🧹 Nitpick comments (6)
playgrounds/contract-first/src/main.ts (1)
30-39:UndefinedErrorschema entry added – looks good but validate generator supportThe new entry aligns with the pattern
{ error: 'UndefinedError' }introduced in the OpenAPI generator.
Two quick follow-ups:
- Make sure every consuming project is running the version of
@orpc/openapithat actually understands theerrorshorthand; otherwise generation will silently drop the component.- This identical
commonSchemasblock now appears in 8+ playgrounds. Consider exporting a shared constant (e.g.playgrounds/shared/commonSchemas.ts) to avoid copy-paste drift.playgrounds/tanstack-start/src/routes/api/$.ts (1)
38-38: Consider centralising theUndefinedErroridentifier.
'UndefinedError'is now hard-coded in several playgrounds. A single exported constant (e.g.UNDEFINED_ERROR_CODE = 'UndefinedError') shared across packages would prevent typos and make future refactors trivial.Are there any other files that still embed this literal that could be switched to the constant?
apps/content/docs/openapi/openapi-specification.md (1)
139-151: Docs look good – tiny formatting nit.The bullet list mixes “sentence” items (ending with periods) and “phrase” items (no period). Aligning them improves readability.
-`UndefinedError` is used for undefined errors, which is very useful when using [Type-Safe Error Handling](/docs/error-handling#type‐safe-error-handling) +`UndefinedError` is used for undefined errors, which is very useful when using [Type-Safe Error Handling](/docs/error-handling#type‐safe-error-handling).packages/openapi/src/openapi-generator.test.ts (2)
1085-1088: Schema name / payload string mismatch might cause confusion.The schema is registered as
UndefinedError2, yet the payload string remains'UndefinedError'.
While technically harmless, aligning the string with the schema name (or vice-versa) avoids head-scratching for future maintainers who grep forUndefinedError2expecting to see it inside the schema body.-UndefinedError2: { - error: 'UndefinedError', +UndefinedError2: { + error: 'UndefinedError2',or rename the component back to
UndefinedError.
1174-1215: Repeated error-object expectations – consider extracting a helper.The same inline object describing the undefined error shape is duplicated several times in this test file. Extracting a reusable matcher, e.g.:
const undefinedErrorRef = { $ref: '#/components/schemas/UndefinedError2' };or a
const undefinedErrorShape = expect.objectContaining({ … })would reduce duplication and ease future updates.packages/openapi/src/openapi-generator.ts (1)
58-61: Narrow the “UndefinedError” discriminator type
{ error: 'UndefinedError' }currently allows any extra keys.
Consider tightening the type so that only theerrorliteral —and nothing else—can be supplied.
Example:commonSchemas?: Record<string, | { schema: AnySchema; strategy?: SchemaConvertOptions['strategy'] } | { error: 'UndefinedError' } & Record<never, never> // forbid additional fields >This prevents silent mis-configuration (e.g.
{ error: 'UndefinedError', typo: true }).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
apps/content/docs/openapi/openapi-specification.md(1 hunks)packages/openapi/src/openapi-generator.test.ts(5 hunks)packages/openapi/src/openapi-generator.ts(10 hunks)playgrounds/astro/src/pages/api/[...rest].ts(1 hunks)playgrounds/contract-first/src/main.ts(1 hunks)playgrounds/nest/src/reference/reference.service.ts(1 hunks)playgrounds/next/src/app/api/[[...rest]]/route.ts(1 hunks)playgrounds/nuxt/server/routes/api/[...].ts(1 hunks)playgrounds/solid-start/src/routes/api/[...rest].ts(1 hunks)playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts(1 hunks)playgrounds/tanstack-start/src/routes/api/$.ts(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: publish-commit
🔇 Additional comments (2)
packages/openapi/src/openapi-generator.test.ts (1)
1260-1274:Details
✅ Verification successful
Ensure all new
$reftargets exist incomponents.schemas.The test adds
$ref: '#/components/schemas/UndefinedError2'; the earlier block registers the component, so the reference should resolve. If more tests start using a different playground name (e.g.UndefinedErrorwithout the2suffix), they will break. A quick grep ensures no stray references slipped in.
🏁 Script executed:
#!/bin/bash # Verify there is no unresolved UndefinedError schema reference. rg --no-heading -n '$ref: .+#/components/schemas/UndefinedError(?!2)' packages/openapi/src | headLength of output: 394
🏁 Script executed:
#!/bin/bash # Re-verify there is no $ref to UndefinedError without the '2' suffix using PCRE2 rg --no-heading -n --pcre2 "\$ref:.*#/components/schemas/UndefinedError(?!2)" packages/openapi/src | headLength of output: 106
All new
$reftargets are defined and no stray references found.
I ran anrg --pcre2 "\$ref:.*#/components/schemas/UndefinedError(?!2)"check againstpackages/openapi/srcand confirmed there are no occurrences of#/components/schemas/UndefinedErrorwithout the2suffix. No further action needed.packages/openapi/src/openapi-generator.ts (1)
510-553: Undefined error added to all error responses – deliberate?
undefinedErrorSchemais appended to every status’oneOf.
If the intent is to expose it only for unexpected/5xx errors, confine it:- oneOf: [ ...schemas, undefinedErrorSchema ] + oneOf: +status.startsWith('5') ? [...schemas, undefinedErrorSchema] : schemasOtherwise API consumers may believe a 400 can legitimately carry an
“undefined” error shape.
1 participant
UndefinedErroris used for undefined errors, which is very useful when using Type-Safe Error Handling.Summary by CodeRabbit
New Features
Documentation
Tests