feat: schema examples #149
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
WalkthroughThis pull request introduces comprehensive changes to handle multiple request body examples in the OpenAPI specification. The modifications span across multiple components, focusing on enhancing the documentation and user interface for displaying examples. The changes include updating the OpenAPI JSON file with concrete examples for artists and users, modifying Vue components to support example-based rendering, and introducing new utility functions for generating and managing schema examples. Changes
Assessment against linked issues
Possibly related PRs
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🔇 Additional comments (3)
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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 (
|
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: 10
🔭 Outside diff range comments (2)
docs/public/openapi.json (2)
Line range hint
107-154: Consider using environment-specific URLs.The hardcoded CDN URLs (
https://cdn.rock-legends.com) might need to be environment-specific.Consider using environment variables or configuration to make the URLs configurable:
- "image": "https://cdn.rock-legends.com/photos/charly.jpg", + "image": "{{% cdn_url %}}/photos/charly.jpg",
Line range hint
401-424: Consider security implications of example passwords.The example passwords in the user signup examples might inadvertently suggest password patterns to users. Consider using more complex passwords in the examples to promote better security practices.
"Carlos": { "value": { "name": "Carlos", "email": "carlos@rock-legends.com", - "password": "i-love-rock" + "password": "P@ssw0rd!2024#Complex" } },
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
⛔ Files ignored due to path filters (1)
test/lib/__snapshots__/processOpenAPI.test.ts.snapis excluded by!**/*.snap
📒 Files selected for processing (15)
docs/public/openapi.json(2 hunks)src/components/Path/OAPath.vue(2 hunks)src/components/Playground/OAPlaygroundParameters.vue(2 hunks)src/components/Request/OARequestBody.vue(1 hunks)src/components/Response/OAResponse.vue(2 hunks)src/components/Schema/OASchemaTabs.vue(4 hunks)src/components/Try/OATryWithVariables.vue(2 hunks)src/composables/useTheme.ts(4 hunks)src/lib/examples/getSchemaExample.ts(1 hunks)src/lib/examples/getSchemaUiJson.ts(1 hunks)src/lib/examples/getSchemaUiXml.ts(1 hunks)src/lib/getSchemaUiContentType.ts(0 hunks)src/lib/processOpenAPI.ts(3 hunks)src/types.ts(1 hunks)test/lib/getSchemaUi.test.ts(2 hunks)
💤 Files with no reviewable changes (1)
- src/lib/getSchemaUiContentType.ts
🧰 Additional context used
🪛 eslint
src/lib/examples/getSchemaUiJson.ts
[error] 1-1: 'OpenAPI' is defined but never used.
(unused-imports/no-unused-imports)
🔇 Additional comments (15)
src/components/Request/OARequestBody.vue (1)
25-25: LGTM! Clean prop update for schema examples supportThe change correctly updates the
OASchemaTabscomponent to use the newexamplesprop, maintaining proper optional chaining for type safety.src/types.ts (1)
70-72: LGTM! Clean type definition for example objectsThe
OAExampleObjecttype correctly extends the OpenAPI type with an optional flag for auto-generated examples.src/components/Response/OAResponse.vue (1)
38-38: LGTM! Consistent implementation of schema examplesThe changes correctly implement the new examples feature:
- Computed property properly derives examples from the content
- OASchemaTabs component receives the examples prop consistently
Also applies to: 88-88
src/components/Try/OATryWithVariables.vue (2)
63-64: LGTM! Clean implementation of examples extraction.The computed property correctly extracts examples from the request body content based on the content type.
76-76: LGTM! Clean prop updates.The changes correctly update the component to use the new examples-based approach:
hasParametersnow checks for body presence usinghasBody- Template correctly passes examples to child component
Also applies to: 90-90
src/components/Schema/OASchemaTabs.vue (1)
Line range hint
76-95: LGTM! Well-structured example content rendering.The template correctly handles:
- Optional example description with markdown
- Example value with proper language highlighting
- Fallback to 'json' for language
src/lib/examples/getSchemaUiJson.ts (1)
7-8: LGTM! Clean extraction of JSON conversion logic.The new
schemaUiToJsonfunction:
- Correctly handles both array and single property cases
- Maintains the existing functionality while improving code organization
Also applies to: 10-15
src/components/Playground/OAPlaygroundParameters.vue (2)
45-48: LGTM! New examples prop added.The new
examplesprop is correctly defined as an optional object property.
87-87: Verify null safety in body initialization.The body initialization uses optional chaining, but there might be edge cases where
props.examplesis an empty object. Consider adding a type guard or default value for better null safety.src/components/Path/OAPath.vue (1)
26-28: LGTM! Operation data initialization.The operation data is correctly initialized and provided to child components.
src/composables/useTheme.ts (1)
23-23: LGTM! Type definitions updated consistently.The 'autogenerated' option has been added consistently across all relevant type definitions.
Also applies to: 123-123, 233-233
test/lib/getSchemaUi.test.ts (1)
5-5: LGTM! Import statement updated.The import has been correctly updated to use the new
getSchemaExamplefunction.src/lib/examples/getSchemaUiXml.ts (1)
2-2: Verify the import path for OAProperty type.Let's ensure the new import path is correct and the file exists.
✅ Verification successful
Import path for OAProperty is correct
The import path '../getSchemaUi' is valid and consistently used across multiple files in the examples directory.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the existence of getSchemaUi.ts in the parent directory # and check for any other files importing OAProperty # Check if the file exists fd --type f "getSchemaUi.ts" src/lib # Check for other imports of OAProperty to ensure consistency rg --type ts "import.*OAProperty.*from" src/Length of output: 361
docs/public/openapi.json (2)
107-123: LGTM! Well-structured examples for artist creation.The examples are meaningful, follow the schema requirements, and provide good coverage of the API's capabilities. Both examples use HTTPS for image URLs and include all required fields.
136-154: LGTM! Response examples maintain consistency with request examples.The response examples correctly include the additional
idfield and maintain consistency with the request examples.
There was a problem hiding this comment.
Actionable comments posted: 3
🔭 Outside diff range comments (1)
src/lib/examples/getSchemaUiJson.ts (1)
Line range hint
9-92: Enhance type safety and input validation throughout the module.Several functions lack explicit return types and input validation, which could lead to type-related issues.
Specify return types for functions, e.g.:
-function uiPropertyToJson(property: OAProperty, useExample: boolean): any { +function uiPropertyToJson(property: OAProperty, useExample: boolean): unknown {Add input validation where necessary to prevent runtime errors.
Implementing these changes will improve the robustness and maintainability of the code.
♻️ Duplicate comments (3)
src/components/Schema/OASchemaTabs.vue (1)
13-15: 🧹 Nitpick (assertive)Consider adding type safety for the
examplesprop.The current
type: nullallows any type, which could lead to runtime errors. Defining a specific type enhances type safety and maintainability.You can apply this diff to add type safety:
+import { PropType } from 'vue' examples: { - type: null, + type: Object as PropType<Record<string, { + description?: string; + value?: any; + lang?: string; + isAutogenerated?: boolean; + }>>, required: false, + default: () => ({}), },src/lib/examples/getSchemaExample.ts (2)
18-34: 🧹 Nitpick (assertive)Add input validation for
uiPropertiesto prevent runtime errors.The function
getSchemaExampleValuelacks validation for theuiPropertiesparameter, which could lead to runtime errors ifuiPropertiesisnullorundefined.Consider adding validation at the start of the function:
function getSchemaExampleValue(contentType: string, uiProperties: OAProperty[] | OAProperty, useExample = false): OAExampleObject { + if (!uiProperties) { + throw new Error('uiProperties is required') + } if (isXml(contentType)) { return { summary: 'XML', description: '', value: getSchemaUiXml(uiProperties, useExample), isAutogenerated: true, } as OAExampleObject } return { summary: 'JSON', description: '', value: getSchemaUiJson(uiProperties, useExample), isAutogenerated: true, } as OAExampleObject }This ensures that the function handles invalid inputs gracefully.
36-38: 🧹 Nitpick (assertive)Enhance the XML content type detection with a more precise regular expression.
The current regular expression could match unintended content types. Refining it improves accuracy.
Update the
isXmlfunction as follows:function isXml(contentType: string): boolean { - return contentType.toLowerCase().match(/^(text|application)\/.*xml($|;|\\+)/) !== null + return /^(application|text)\/(.+\+)?xml(;.*)?$/i.test(contentType) }This regex matches content types like
application/xmlandapplication/atom+xml, providing more precise detection.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (3)
src/components/Schema/OASchemaTabs.vue(4 hunks)src/lib/examples/getSchemaExample.ts(1 hunks)src/lib/examples/getSchemaUiJson.ts(1 hunks)
🔇 Additional comments (1)
src/components/Schema/OASchemaTabs.vue (1)
25-38: 🧹 Nitpick (assertive)Simplify the
defaultValuecomputed property for clarity.The
defaultValuelogic can be further simplified to improve readability by avoiding the use of an immediately invoked function expression (IIFE) within theviewMap.Consider refactoring as follows:
const defaultValue = computed(() => { const defaultView = themeConfig.schemaConfig.defaultView.value const examplesKeys = Object.keys(props.examples ?? {}) - const viewMap = { + if (defaultView === 'schema') { + return 'schema' + } else if (defaultView === 'contentType') { + return examplesKeys.length ? `examples.${examplesKeys[0]}` : 'schema' + } else if (defaultView === 'autogenerated') { + const autogeneratedExample = examplesKeys.find( + key => props.examples[key]?.isAutogenerated + ) + return autogeneratedExample ? `examples.${autogeneratedExample}` : 'schema' + } else { + return defaultView + } })This refactoring enhances readability by using straightforward conditional statements.
Likely invalid or redundant comment.
Description
Allows to handle schema examples.
Related issues/external references
Closes #141
Types of changes