@gitbook/react-openapi 1.1.3 → 1.1.4

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.1.3",
+    "version": "1.1.4",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",

package/src/OpenAPICodeSample.tsx

@@ -26,13 +26,17 @@ export function OpenAPICodeSample(props: {
         }
 
         if (param.in === 'header' && param.required) {
-            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
+            const example = param.schema
+                ? generateSchemaExample(param.schema, { mode: 'write' })
+                : undefined;
             if (example !== undefined && param.name) {
                 headersObject[param.name] =
                     typeof example !== 'string' ? stringifyOpenAPI(example) : example;
             }
         } else if (param.in === 'query' && param.required) {
-            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
+            const example = param.schema
+                ? generateSchemaExample(param.schema, { mode: 'write' })
+                : undefined;
             if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,

package/src/OpenAPISchemaName.tsx

@@ -30,6 +30,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                     <span className="openapi-schema-type">{additionalItems}</span>
                 ) : null}
             </span>
+            {schema?.readOnly ? <span className="openapi-schema-readonly">read-only</span> : null}
             {required ? <span className="openapi-schema-required">required</span> : null}
             {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
         </div>

package/src/schemas/OpenAPISchemas.tsx

@@ -4,13 +4,18 @@ import { OpenAPIRootSchema } from '../OpenAPISchema';
 import { Section, SectionBody } from '../StaticSection';
 import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPISchemasData } from '../types';
 
+type OpenAPISchemasContextProps = Omit<
+    OpenAPIContextProps,
+    'renderCodeBlock' | 'renderHeading' | 'renderDocument'
+>;
+
 /**
  * Display OpenAPI Schemas.
  */
 export function OpenAPISchemas(props: {
     className?: string;
     data: OpenAPISchemasData;
-    context: OpenAPIContextProps;
+    context: OpenAPISchemasContextProps;
 }) {
     const { className, data, context } = props;
     const { schemas } = data;

package/src/schemas/resolveOpenAPISchemas.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'bun:test';
+
+import { parseOpenAPI, traverse } from '@gitbook/openapi-parser';
+import { resolveOpenAPISchemas } from './resolveOpenAPISchemas';
+
+async function fetchFilesystem(url: string) {
+    const response = await fetch(url);
+    const text = await response.text();
+    const filesystem = await parseOpenAPI({ value: text, rootURL: url });
+    const transformedFs = await traverse(filesystem, async (node) => {
+        if ('description' in node && typeof node.description === 'string' && node.description) {
+            node['x-gitbook-description-html'] = node.description;
+        }
+        return node;
+    });
+    return transformedFs;
+}
+
+describe('#resolveOpenAPISchemas', () => {
+    it('should resolve refs', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.json'
+        );
+        const resolved = await resolveOpenAPISchemas(filesystem, { schemas: ['Pet', 'Tag'] });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'Pet',
+                    schema: {
+                        properties: {
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        id: {
+                                            format: 'int64',
+                                            type: 'integer',
+                                        },
+                                        name: {
+                                            type: 'string',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                {
+                    name: 'Tag',
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'integer',
+                                format: 'int64',
+                            },
+                            name: {
+                                type: 'string',
+                            },
+                        },
+                        xml: {
+                            name: 'tag',
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('should support yaml', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.yaml'
+        );
+        const resolved = await resolveOpenAPISchemas(filesystem, { schemas: ['Pet'] });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'Pet',
+                    schema: {
+                        properties: {
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    properties: {
+                                        id: {
+                                            format: 'int64',
+                                            type: 'integer',
+                                        },
+                                        name: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('should resolve circular refs', async () => {
+        const filesystem = await fetchFilesystem('https://api.gitbook.com/openapi.json');
+        const resolved = await resolveOpenAPISchemas(filesystem, {
+            schemas: ['DocumentBlockTabs'],
+        });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'DocumentBlockTabs',
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            object: {
+                                type: 'string',
+                                enum: ['block'],
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('should resolve to null if the schema does not exist', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.json'
+        );
+        const resolved = await resolveOpenAPISchemas(filesystem, {
+            schemas: ['NonExistentSchema'],
+        });
+
+        expect(resolved).toBe(null);
+    });
+
+    it('should parse Swagger 2.0', async () => {
+        const filesystem = await fetchFilesystem('https://petstore.swagger.io/v2/swagger.json');
+        const resolved = await resolveOpenAPISchemas(filesystem, {
+            schemas: ['Pet'],
+        });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'Pet',
+                    schema: {
+                        properties: {
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    properties: {
+                                        id: {
+                                            format: 'int64',
+                                            type: 'integer',
+                                        },
+                                        name: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+});

package/src/schemas/resolveOpenAPISchemas.ts

@@ -15,21 +15,43 @@ import type { OpenAPISchema, OpenAPISchemasData } from '../types';
  * Schemas are extracted from the OpenAPI components.schemas
  */
 export async function resolveOpenAPISchemas(
-    filesystem: Filesystem<OpenAPIV3xDocument>
+    filesystem: Filesystem<OpenAPIV3xDocument>,
+    options: {
+        schemas: string[];
+    }
 ): Promise<OpenAPISchemasData | null> {
+    const { schemas: selectedSchemas } = options;
+
     const schema = await dereferenceFilesystem(filesystem);
 
-    const schemas = getOpenAPIComponents(schema);
+    const schemas = filterSelectedOpenAPISchemas(schema, selectedSchemas);
+
+    if (schemas.length === 0) {
+        return null;
+    }
 
     return { schemas };
 }
-
 /**
- * Get OpenAPI components.schemas that are not ignored.
+ * Extract selected schemas from the OpenAPI document.
  */
-function getOpenAPIComponents(schema: OpenAPIV3.Document | OpenAPIV3_1.Document): OpenAPISchema[] {
-    const schemas = schema.components?.schemas ?? {};
-    return Object.entries(schemas)
-        .filter(([, schema]) => !shouldIgnoreEntity(schema))
-        .map(([key, schema]) => ({ name: key, schema }));
+export function filterSelectedOpenAPISchemas(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    selectedSchemas: string[]
+): OpenAPISchema[] {
+    const componentsSchemas = schema.components?.schemas ?? {};
+
+    // Preserve the order of the selected schemas
+    return selectedSchemas
+        .map((name) => {
+            const schema = componentsSchemas[name];
+            if (schema && !shouldIgnoreEntity(schema)) {
+                return {
+                    name,
+                    schema,
+                };
+            }
+            return null;
+        })
+        .filter((schema): schema is OpenAPISchema => !!schema);
 }