@gitbook/react-openapi 1.3.0 → 1.3.1

package/dist/utils.d.ts

@@ -47,3 +47,4 @@ export declare function getStatusCodeClassName(statusCode: number | string): str
  * 4xx, 5xx: Error
  */
 export declare function getStatusCodeDefaultLabel(statusCode: number | string, context: OpenAPIUniversalContext): string;
+export declare function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string;

package/dist/utils.js

@@ -184,3 +184,41 @@ function getStatusCodeCategory(statusCode) {
     var category = Math.floor(code / 100);
     return category;
 }
+export function getSchemaTitle(schema) {
+    var _a;
+    // Otherwise try to infer a nice title
+    var type = 'any';
+    if (schema.enum || schema['x-enumDescriptions'] || schema['x-gitbook-enum']) {
+        type = "".concat(schema.type, " \u00B7 enum");
+        // check array AND schema.items as this is sometimes null despite what the type indicates
+    }
+    else if (schema.type === 'array' && !!schema.items) {
+        type = "".concat(getSchemaTitle(schema.items), "[]");
+    }
+    else if (Array.isArray(schema.type)) {
+        type = schema.type.join(' | ');
+    }
+    else if (schema.type || schema.properties) {
+        type = (_a = schema.type) !== null && _a !== void 0 ? _a : 'object';
+        if (schema.format) {
+            type += " \u00B7 ".concat(schema.format);
+        }
+        // Only add the title if it's an object (no need for the title of a string, number, etc.)
+        if (type === 'object' && schema.title) {
+            type += " \u00B7 ".concat(schema.title.replaceAll(' ', ''));
+        }
+    }
+    if ('anyOf' in schema) {
+        type = 'any of';
+    }
+    else if ('oneOf' in schema) {
+        type = 'one of';
+    }
+    else if ('allOf' in schema) {
+        type = 'all of';
+    }
+    else if ('not' in schema) {
+        type = 'not';
+    }
+    return type;
+}

package/package.json

@@ -8,11 +8,11 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.3.0",
+    "version": "1.3.1",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
-        "@scalar/api-client-react": "^1.2.19",
+        "@scalar/api-client-react": "^1.3.16",
         "@scalar/oas-utils": "^0.2.130",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",

package/src/OpenAPICodeSample.tsx

@@ -253,15 +253,11 @@ function getCustomCodeSamples(props: {
         if (customSamples && Array.isArray(customSamples)) {
             customCodeSamples = customSamples
                 .filter((sample) => {
-                    return (
-                        typeof sample.label === 'string' &&
-                        typeof sample.source === 'string' &&
-                        typeof sample.lang === 'string'
-                    );
+                    return typeof sample.source === 'string' && typeof sample.lang === 'string';
                 })
                 .map((sample, index) => ({
                     key: `custom-sample-${sample.lang}-${index}`,
-                    label: sample.label,
+                    label: sample.label || sample.lang,
                     body: context.renderCodeBlock({
                         code: sample.source,
                         syntax: sample.lang,
@@ -312,6 +308,11 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
                 [name]: 'YOUR_API_KEY',
             };
         }
+        case 'oauth2': {
+            return {
+                Authorization: 'Bearer YOUR_OAUTH2_TOKEN',
+            };
+        }
         default: {
             return {};
         }

package/src/OpenAPIRequestBody.tsx

@@ -1,5 +1,6 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { InteractiveSection } from './InteractiveSection';
+import { OpenAPIRequestBodyHeaderType } from './OpenAPIRequestBodyHeaderType';
 import { OpenAPIRootSchema } from './OpenAPISchemaServer';
 import type { OpenAPIClientContext } from './context';
 import { t } from './translate';
@@ -20,11 +21,18 @@ export function OpenAPIRequestBody(props: {
         return null;
     }
 
+    const stateKey = createStateKey('request-body-media-type', context.blockKey);
+
     return (
         <InteractiveSection
-            header={t(context.translation, 'name' in data ? 'payload' : 'body')}
+            header={
+                <>
+                    <span>{t(context.translation, 'name' in data ? 'payload' : 'body')}</span>
+                    <OpenAPIRequestBodyHeaderType requestBody={requestBody} stateKey={stateKey} />
+                </>
+            }
             className="openapi-requestbody"
-            stateKey={createStateKey('request-body-media-type', context.blockKey)}
+            stateKey={stateKey}
             selectIcon={context.icons.chevronDown}
             tabs={Object.entries(requestBody.content ?? {}).map(
                 ([contentType, mediaTypeObject]) => {
@@ -35,6 +43,7 @@ export function OpenAPIRequestBody(props: {
                             <OpenAPIRootSchema
                                 schema={mediaTypeObject.schema ?? {}}
                                 context={context}
+                                key={contentType}
                             />
                         ),
                     };

package/src/OpenAPIRequestBodyHeaderType.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { useSelectState } from './OpenAPISelect';
+import { getSchemaTitle } from './utils';
+
+/**
+ * Display the type of a request body. It only displays the type if the selected content is an array.
+ */
+export function OpenAPIRequestBodyHeaderType(props: {
+    requestBody: OpenAPIV3.RequestBodyObject;
+    stateKey: string;
+}) {
+    const { requestBody, stateKey } = props;
+    const content = requestBody.content ?? {};
+    const state = useSelectState(stateKey, Object.keys(content)[0]);
+
+    const selectedContentMediaType = Object.entries(content).find(
+        ([contentType]) => contentType === state.key
+    )?.[1];
+
+    // If the selected content is not an array, we don't display the type
+    if (
+        !selectedContentMediaType ||
+        !selectedContentMediaType.schema?.type ||
+        selectedContentMediaType.schema.type !== 'array'
+    ) {
+        return null;
+    }
+
+    return (
+        <span className="openapi-requestbody-header-type">
+            {`${getSchemaTitle(selectedContentMediaType.schema)}`}
+        </span>
+    );
+}

package/src/OpenAPIResponse.tsx

@@ -11,14 +11,14 @@ import { parameterToProperty, resolveDescription } from './utils';
  */
 export function OpenAPIResponse(props: {
     response: OpenAPIV3.ResponseObject;
-    mediaType: OpenAPIV3.MediaTypeObject;
+    mediaType: OpenAPIV3.MediaTypeObject | null;
     context: OpenAPIClientContext;
 }) {
     const { response, context, mediaType } = props;
     const headers = Object.entries(response.headers ?? {}).map(
         ([name, header]) => [name, header ?? {}] as const
     );
-    const content = Object.entries(mediaType.schema ?? {});
+    const content = Object.entries(mediaType?.schema ?? {});
 
     const description = resolveDescription(response);
 
@@ -62,7 +62,7 @@ export function OpenAPIResponse(props: {
                     />
                 </OpenAPIDisclosure>
             ) : null}
-            {mediaType.schema && (
+            {mediaType?.schema && (
                 <div className="openapi-responsebody">
                     <OpenAPISchemaProperties
                         id={`response-${context.blockKey}`}

package/src/OpenAPIResponseExample.tsx

@@ -99,7 +99,7 @@ export function OpenAPIResponseExample(props: {
 function OpenAPIResponse(props: {
     context: OpenAPIContext;
     content: {
-        [media: string]: OpenAPIV3.MediaTypeObject;
+        [media: string]: OpenAPIV3.MediaTypeObject | null;
     };
 }) {
     const { context, content } = props;
@@ -113,6 +113,15 @@ function OpenAPIResponse(props: {
 
     const tabs = entries.map((entry) => {
         const [mediaType, mediaTypeObject] = entry;
+
+        if (!mediaTypeObject) {
+            return {
+                key: mediaType,
+                label: mediaType,
+                body: <OpenAPIEmptyExample context={context} />,
+            };
+        }
+
         return {
             key: mediaType,
             label: mediaType,

package/src/OpenAPISchema.tsx

@@ -16,7 +16,7 @@ import { retrocycle } from './decycle';
 import { getDisclosureLabel } from './getDisclosureLabel';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { tString } from './translate';
-import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
+import { checkIsReference, getSchemaTitle, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
@@ -652,40 +652,3 @@ function mergeRequiredFields(
         new Set([...(latestAncestor?.required || []), ...(schemaOrRef.required || [])])
     );
 }
-
-function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
-    // Otherwise try to infer a nice title
-    let type = 'any';
-
-    if (schema.enum || schema['x-enumDescriptions'] || schema['x-gitbook-enum']) {
-        type = `${schema.type} · enum`;
-        // check array AND schema.items as this is sometimes null despite what the type indicates
-    } else if (schema.type === 'array' && !!schema.items) {
-        type = `${getSchemaTitle(schema.items)}[]`;
-    } else if (Array.isArray(schema.type)) {
-        type = schema.type.join(' | ');
-    } else if (schema.type || schema.properties) {
-        type = schema.type ?? 'object';
-
-        if (schema.format) {
-            type += ` · ${schema.format}`;
-        }
-
-        // Only add the title if it's an object (no need for the title of a string, number, etc.)
-        if (type === 'object' && schema.title) {
-            type += ` · ${schema.title.replaceAll(' ', '')}`;
-        }
-    }
-
-    if ('anyOf' in schema) {
-        type = 'any of';
-    } else if ('oneOf' in schema) {
-        type = 'one of';
-    } else if ('allOf' in schema) {
-        type = 'all of';
-    } else if ('not' in schema) {
-        type = 'not';
-    }
-
-    return type;
-}

package/src/OpenAPISchemaName.tsx

@@ -27,12 +27,14 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                     {propertyName}
                 </span>
             ) : null}
-            <span>
-                {type ? <span className="openapi-schema-type">{type}</span> : null}
-                {additionalItems ? (
-                    <span className="openapi-schema-type">{additionalItems}</span>
-                ) : null}
-            </span>
+            {type || additionalItems ? (
+                <span>
+                    {type ? <span className="openapi-schema-type">{type}</span> : null}
+                    {additionalItems ? (
+                        <span className="openapi-schema-type">{additionalItems}</span>
+                    ) : null}
+                </span>
+            ) : null}
             {schema?.readOnly ? (
                 <span className="openapi-schema-readonly">
                     {t(context.translation, 'read_only')}

package/src/OpenAPISecurities.tsx

@@ -1,5 +1,7 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
+import { OpenAPICopyButton } from './OpenAPICopyButton';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import type { OpenAPIClientContext } from './context';
 import { t } from './translate';
@@ -105,13 +107,7 @@ function getLabelForType(security: OpenAPISecurityWithRequired, context: OpenAPI
                 />
             );
         case 'oauth2':
-            return (
-                <OpenAPISchemaName
-                    context={context}
-                    propertyName="OAuth2"
-                    required={security.required}
-                />
-            );
+            return <OpenAPISchemaOAuth2Flows context={context} security={security} />;
         case 'openIdConnect':
             return (
                 <OpenAPISchemaName
@@ -125,3 +121,111 @@ function getLabelForType(security: OpenAPISecurityWithRequired, context: OpenAPI
             return security.type;
     }
 }
+
+function OpenAPISchemaOAuth2Flows(props: {
+    context: OpenAPIClientContext;
+    security: OpenAPIV3.OAuth2SecurityScheme & { required?: boolean };
+}) {
+    const { context, security } = props;
+
+    const flows = Object.entries(security.flows ?? {});
+
+    return (
+        <div className="openapi-securities-oauth-flows">
+            {flows.map(([name, flow], index) => (
+                <OpenAPISchemaOAuth2Item
+                    key={index}
+                    flow={flow}
+                    name={name}
+                    context={context}
+                    security={security}
+                />
+            ))}
+        </div>
+    );
+}
+
+function OpenAPISchemaOAuth2Item(props: {
+    flow: NonNullable<OpenAPIV3.OAuth2SecurityScheme['flows']>[keyof NonNullable<
+        OpenAPIV3.OAuth2SecurityScheme['flows']
+    >];
+    name: string;
+    context: OpenAPIClientContext;
+    security: OpenAPIV3.OAuth2SecurityScheme & { required?: boolean };
+}) {
+    const { flow, context, security, name } = props;
+
+    if (!flow) {
+        return null;
+    }
+
+    const scopes = Object.entries(flow?.scopes ?? {});
+
+    return (
+        <div>
+            <OpenAPISchemaName
+                context={context}
+                propertyName="OAuth2"
+                type={name}
+                required={security.required}
+            />
+            <div className="openapi-securities-oauth-content openapi-markdown">
+                {security.description ? <Markdown source={security.description} /> : null}
+                {'authorizationUrl' in flow && flow.authorizationUrl ? (
+                    <span>
+                        Authorization URL:{' '}
+                        <OpenAPICopyButton
+                            value={flow.authorizationUrl}
+                            context={context}
+                            className="openapi-securities-url"
+                            withTooltip
+                        >
+                            {flow.authorizationUrl}
+                        </OpenAPICopyButton>
+                    </span>
+                ) : null}
+                {'tokenUrl' in flow && flow.tokenUrl ? (
+                    <span>
+                        Token URL:{' '}
+                        <OpenAPICopyButton
+                            value={flow.tokenUrl}
+                            context={context}
+                            className="openapi-securities-url"
+                            withTooltip
+                        >
+                            {flow.tokenUrl}
+                        </OpenAPICopyButton>
+                    </span>
+                ) : null}
+                {'refreshUrl' in flow && flow.refreshUrl ? (
+                    <span>
+                        Refresh URL:{' '}
+                        <OpenAPICopyButton
+                            value={flow.refreshUrl}
+                            context={context}
+                            className="openapi-securities-url"
+                            withTooltip
+                        >
+                            {flow.refreshUrl}
+                        </OpenAPICopyButton>
+                    </span>
+                ) : null}
+                {scopes.length ? (
+                    <div>
+                        {t(context.translation, 'available_scopes')}:{' '}
+                        <ul>
+                            {scopes.map(([key, value]) => (
+                                <li key={key}>
+                                    <OpenAPICopyButton value={key} context={context} withTooltip>
+                                        <code>{key}</code>
+                                    </OpenAPICopyButton>
+                                    : {value}
+                                </li>
+                            ))}
+                        </ul>
+                    </div>
+                ) : null}
+            </div>
+        </div>
+    );
+}

package/src/OpenAPISelect.tsx

@@ -33,7 +33,7 @@ interface OpenAPISelectProps<T extends OpenAPISelectItem> extends Omit<SelectPro
     icon?: React.ReactNode;
 }
 
-export function useSelectState(stateKey = 'select-state', initialKey?: Key) {
+export function useSelectState(stateKey = 'select-state', initialKey: Key = 'default') {
     const store = useStore(getOrCreateStoreByKey(stateKey, initialKey));
     return {
         key: store.key,

package/src/OpenAPISpec.tsx

@@ -18,7 +18,7 @@ export function OpenAPISpec(props: {
 
     const { operation } = data;
 
-    const parameters = operation.parameters ?? [];
+    const parameters = deduplicateParameters(operation.parameters ?? []);
     const parameterGroups = groupParameters(parameters, context);
 
     const securities = 'securities' in data ? data.securities : [];
@@ -113,3 +113,23 @@ function getParameterGroupName(paramIn: string, context: OpenAPIClientContext):
             return paramIn;
     }
 }
+
+/** Deduplicate parameters by name and in.
+ * Some specs have both parameters define at path and operation level.
+ * We only want to display one of them.
+ */
+function deduplicateParameters(parameters: OpenAPI.Parameters): OpenAPI.Parameters {
+    const seen = new Set();
+
+    return parameters.filter((param) => {
+        const key = `${param.name}:${param.in}`;
+
+        if (seen.has(key)) {
+            return false;
+        }
+
+        seen.add(key);
+
+        return true;
+    });
+}

package/src/OpenAPIWebhookExample.tsx

@@ -19,9 +19,9 @@ export function OpenAPIWebhookExample(props: {
         }
 
         return Object.entries(
-            operation.requestBody.content as Record<string, OpenAPIV3.MediaTypeObject>
+            operation.requestBody.content as Record<string, OpenAPIV3.MediaTypeObject | null>
         ).map(([key, value]) => {
-            const schema = value.schema;
+            const schema = value?.schema;
 
             if (!schema) {
                 return {

package/src/code-samples.test.ts

@@ -400,7 +400,7 @@ describe('python code sample generator', () => {
         const output = generator?.generate(input);
 
         expect(output).toBe(
-            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/x-www-form-urlencoded"},\n    data={"key":"value"}\n)\n\ndata = response.json()'
+            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/x-www-form-urlencoded"},\n    data={\n      "key": "value"\n    }\n)\n\ndata = response.json()'
         );
     });
 
@@ -422,7 +422,7 @@ describe('python code sample generator', () => {
         const output = generator?.generate(input);
 
         expect(output).toBe(
-            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/json"},\n    data=json.dumps({"key":"value","truethy":True,"falsey":False,"nullish":None})\n)\n\ndata = response.json()'
+            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/json"},\n    data=json.dumps({\n      "key": "value",\n      "truethy": True,\n      "falsey": False,\n      "nullish": None\n    })\n)\n\ndata = response.json()'
         );
     });
 

package/src/code-samples.ts

@@ -356,18 +356,22 @@ const BodyGenerators = {
             // Convert JSON to XML if needed
             body = JSON.stringify(convertBodyToXML(body));
         } else {
-            body = stringifyOpenAPI(body, (_key, value) => {
-                switch (value) {
-                    case true:
-                        return '$$__TRUE__$$';
-                    case false:
-                        return '$$__FALSE__$$';
-                    case null:
-                        return '$$__NULL__$$';
-                    default:
-                        return value;
-                }
-            })
+            body = stringifyOpenAPI(
+                body,
+                (_key, value) => {
+                    switch (value) {
+                        case true:
+                            return '$$__TRUE__$$';
+                        case false:
+                            return '$$__FALSE__$$';
+                        case null:
+                            return '$$__NULL__$$';
+                        default:
+                            return value;
+                    }
+                },
+                2
+            )
                 .replaceAll('"$$__TRUE__$$"', 'True')
                 .replaceAll('"$$__FALSE__$$"', 'False')
                 .replaceAll('"$$__NULL__$$"', 'None');

package/src/generateSchemaExample.test.ts

@@ -1017,4 +1017,24 @@ describe('generateSchemaExample', () => {
             },
         });
     });
+
+    it('handles deprecated properties', () => {
+        expect(
+            generateSchemaExample({
+                type: 'object',
+                deprecated: true,
+            })
+        ).toBeUndefined();
+    });
+
+    it('handle nested deprecated properties', () => {
+        expect(
+            generateSchemaExample({
+                type: 'array',
+                items: {
+                    deprecated: true,
+                },
+            })
+        ).toBeUndefined();
+    });
 });

package/src/generateSchemaExample.ts

@@ -167,7 +167,7 @@ const getExampleFromSchema = (
     const makeUpRandomData = !!options?.emptyString;
 
     // If the property is deprecated we don't show it in examples.
-    if (schema.deprecated) {
+    if (schema.deprecated || (schema.type === 'array' && schema.items?.deprecated)) {
         return undefined;
     }
 

package/src/translations/de.ts

@@ -35,6 +35,7 @@ export const de = {
     show: 'Zeige ${1}',
     hide: 'Verstecke ${1}',
     available_items: 'Verfügbare Elemente',
+    available_scopes: 'Verfügbare scopes',
     properties: 'Eigenschaften',
     or: 'oder',
     and: 'und',

package/src/translations/en.ts

@@ -35,6 +35,7 @@ export const en = {
     show: 'Show ${1}',
     hide: 'Hide ${1}',
     available_items: 'Available items',
+    available_scopes: 'Available scopes',
     possible_values: 'Possible values',
     properties: 'Properties',
     or: 'or',

package/src/translations/es.ts

@@ -35,6 +35,7 @@ export const es = {
     show: 'Mostrar ${1}',
     hide: 'Ocultar ${1}',
     available_items: 'Elementos disponibles',
+    available_scopes: 'Scopes disponibles',
     properties: 'Propiedades',
     or: 'o',
     and: 'y',

package/src/translations/fr.ts

@@ -35,6 +35,7 @@ export const fr = {
     show: 'Afficher ${1}',
     hide: 'Masquer ${1}',
     available_items: 'Éléments disponibles',
+    available_scopes: 'Scopes disponibles',
     properties: 'Propriétés',
     or: 'ou',
     and: 'et',

package/src/translations/ja.ts

@@ -35,6 +35,7 @@ export const ja = {
     show: '${1}を表示',
     hide: '${1}を非表示',
     available_items: '利用可能なアイテム',
+    available_scopes: '利用可能なスコープ',
     properties: 'プロパティ',
     or: 'または',
     and: 'かつ',

package/src/translations/nl.ts

@@ -35,6 +35,7 @@ export const nl = {
     show: 'Toon ${1}',
     hide: 'Verberg ${1}',
     available_items: 'Beschikbare items',
+    available_scopes: 'Beschikbare scopes',
     properties: 'Eigenschappen',
     or: 'of',
     and: 'en',

package/src/translations/no.ts

@@ -35,6 +35,7 @@ export const no = {
     show: 'Vis ${1}',
     hide: 'Skjul ${1}',
     available_items: 'Tilgjengelige elementer',
+    available_scopes: 'Tilgjengelige scopes',
     properties: 'Egenskaper',
     or: 'eller',
     and: 'og',

package/src/translations/pt-br.ts

@@ -35,6 +35,7 @@ export const pt_br = {
     show: 'Mostrar ${1}',
     hide: 'Ocultar ${1}',
     available_items: 'Itens disponíveis',
+    available_scopes: 'Scopes disponíveis',
     properties: 'Propriedades',
     or: 'ou',
     and: 'e',

package/src/translations/zh.ts

@@ -35,6 +35,7 @@ export const zh = {
     show: '显示${1}',
     hide: '隐藏${1}',
     available_items: '可用项',
+    available_scopes: '可用范围',
     properties: '属性',
     or: '或',
     and: '和',