Improve support for OAuth2 security type (#3304)

Author: nolannbiron

.changeset/fifty-ducks-press.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Improve support for OAuth2 security type

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -310,6 +310,26 @@
     @apply py-2 border-b border-tint-subtle max-w-full flex-1;
 }
 
+.openapi-securities-oauth-flows {
+    @apply flex flex-col gap-2 divide-y divide-tint-subtle;
+}
+
+.openapi-securities-oauth-content {
+    @apply prose *:!prose-sm *:text-tint;
+}
+
+.openapi-securities-oauth-content.openapi-markdown code {
+    @apply text-xs;
+}
+
+.openapi-securities-oauth-content ul {
+    @apply !my-0;
+}
+
+.openapi-securities-url {
+    @apply ml-0.5 px-0.5 rounded hover:bg-tint transition-colors;
+}
+
 .openapi-securities-body {
     @apply flex flex-col gap-2;
 }

packages/react-openapi/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')}

packages/react-openapi/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>
+    );
+}

packages/react-openapi/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',

packages/react-openapi/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',

packages/react-openapi/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',

packages/react-openapi/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',

packages/react-openapi/src/translations/ja.ts

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

packages/react-openapi/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',