@gitbook/react-openapi 1.0.1 → 1.0.2

package/src/__snapshots__/json2xml.test.ts.snap

@@ -0,0 +1,18 @@
+// Bun Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`getUrlFromServerState indents correctly 1`] = `
+"<?xml version="1.0"?>
+<id>10</id>
+<name>doggie</name>
+<category>
+	<id>1</id>
+	<name>Dogs</name>
+</category>
+<photoUrls>string</photoUrls>
+<tags>
+	<id>0</id>
+	<name>string</name>
+</tags>
+<status>available</status>
+"
+`;

package/src/generateSchemaExample.ts

@@ -3,18 +3,21 @@ import { getExampleFromSchema } from '@scalar/oas-utils/spec-getters';
 
 type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
 
+type ScalarGetExampleFromSchemaOptions = NonNullable<Parameters<typeof getExampleFromSchema>[1]>;
+type GenerateSchemaExampleOptions = Pick<
+    ScalarGetExampleFromSchemaOptions,
+    'xml' | 'omitEmptyAndOptionalProperties' | 'mode'
+>;
+
 /**
  * Generate a JSON example from a schema
  */
 export function generateSchemaExample(
     schema: OpenAPIV3.SchemaObject,
-    options: {
-        onlyRequired?: boolean;
-    } = {},
+    options?: GenerateSchemaExampleOptions,
 ): JSONValue | undefined {
     return getExampleFromSchema(schema, {
         emptyString: 'text',
-        omitEmptyAndOptionalProperties: options.onlyRequired,
         variables: {
             'date-time': new Date().toISOString(),
             date: new Date().toISOString().split('T')[0],
@@ -28,6 +31,7 @@ export function generateSchemaExample(
             byte: 'Ynl0ZXM=',
             password: 'password',
         },
+        ...options,
     });
 }
 
@@ -36,9 +40,7 @@ export function generateSchemaExample(
  */
 export function generateMediaTypeExample(
     mediaType: OpenAPIV3.MediaTypeObject,
-    options: {
-        onlyRequired?: boolean;
-    } = {},
+    options?: GenerateSchemaExampleOptions,
 ): JSONValue | undefined {
     if (mediaType.example) {
         return mediaType.example;

package/src/json2xml.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'bun:test';
+
+import { json2xml } from './json2xml';
+
+describe('getUrlFromServerState', () => {
+    it('transforms JSON to xml', () => {
+        const xml = json2xml({
+            foo: 'bar',
+        });
+
+        expect(xml).toBe('<?xml version="1.0"?>\n<foo>bar</foo>\n');
+    });
+
+    it('wraps array items', () => {
+        const xml = json2xml({
+            urls: {
+                url: ['https://example.com', 'https://example.com'],
+            },
+        });
+
+        expect(xml).toBe(
+            '<?xml version="1.0"?>\n<urls>\n\t<url>https://example.com</url>\n\t<url>https://example.com</url>\n</urls>\n',
+        );
+    });
+
+    it('indents correctly', () => {
+        const xml = json2xml({
+            id: 10,
+            name: 'doggie',
+            category: {
+                id: 1,
+                name: 'Dogs',
+            },
+            photoUrls: ['string'],
+            tags: [
+                {
+                    id: 0,
+                    name: 'string',
+                },
+            ],
+            status: 'available',
+        });
+
+        expect(xml).toMatchSnapshot();
+    });
+});

package/src/json2xml.ts

@@ -0,0 +1,8 @@
+import { jsXml } from 'json-xml-parse';
+
+/**
+ * This function converts an object to XML.
+ */
+export function json2xml(data: Record<string, any>) {
+    return jsXml.toXmlString(data, { beautify: true });
+}

package/src/resolveOpenAPIOperation.test.ts

@@ -9,7 +9,7 @@ async function fetchFilesystem(url: string) {
     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-description-html'] = node.description;
+            node['x-gitbook-description-html'] = node.description;
         }
         return node;
     });

package/src/types.ts

@@ -6,6 +6,7 @@ import type {
 
 export interface OpenAPIContextProps extends OpenAPIClientContext {
     CodeBlock: React.ComponentType<{ code: string; syntax: string }>;
+    renderHeading: (props: { deprecated: boolean; title: string }) => React.ReactNode;
 
     /** Spec url for the Scalar Api Client */
     specUrl: string;

package/src/utils.ts

@@ -1,6 +1,8 @@
-import type { AnyObject, OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
 
-export function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject {
+export function checkIsReference(
+    input: unknown,
+): input is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
 
@@ -12,9 +14,83 @@ export function createStateKey(key: string, scope?: string) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object: AnyObject) {
-    return 'x-description-html' in object && typeof object['x-description-html'] === 'string'
-        ? object['x-description-html']
+    return 'x-gitbook-description-html' in object &&
+        typeof object['x-gitbook-description-html'] === 'string'
+        ? object['x-gitbook-description-html'].trim()
         : typeof object.description === 'string'
-          ? object.description
+          ? object.description.trim()
           : undefined;
 }
+
+/**
+ * Extract descriptions from an object.
+ */
+export function extractDescriptions(object: AnyObject) {
+    return {
+        description: object.description,
+        ['x-gitbook-description-html']:
+            'x-gitbook-description-html' in object
+                ? object['x-gitbook-description-html']
+                : undefined,
+    };
+}
+
+/**
+ * Resolve the first example from an object.
+ */
+export function resolveFirstExample(object: AnyObject) {
+    if ('examples' in object && typeof object.examples === 'object' && object.examples) {
+        const keys = Object.keys(object.examples);
+        const firstKey = keys[0];
+        if (firstKey && object.examples[firstKey]) {
+            return object.examples[firstKey];
+        }
+    }
+    if ('example' in object && object.example !== undefined) {
+        return object.example;
+    }
+    return undefined;
+}
+
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export function resolveParameterSchema(
+    parameter: OpenAPIV3.ParameterBaseObject,
+): OpenAPIV3.SchemaObject {
+    const schema = checkIsReference(parameter.schema) ? undefined : parameter.schema;
+    return {
+        // Description of the parameter is defined at the parameter level
+        // we use display it if the schema doesn't override it
+        ...extractDescriptions(parameter),
+        example: resolveFirstExample(parameter),
+        // Deprecated can be defined at the parameter level
+        deprecated: parameter.deprecated,
+        ...schema,
+    };
+}
+
+/**
+ * Transform a parameter object to a property object.
+ */
+export function parameterToProperty(
+    parameter: OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject,
+): {
+    propertyName: string | undefined;
+    schema: OpenAPIV3.SchemaObject;
+    required: boolean | undefined;
+} {
+    if (checkIsReference(parameter)) {
+        return {
+            propertyName: parameter.$ref ?? 'Unknown ref',
+            schema: {},
+            required: undefined,
+        };
+    }
+    return {
+        propertyName: parameter.name,
+        schema: resolveParameterSchema(parameter),
+        required: parameter.required,
+    };
+}