From a512c90bdaefebf921fc8d69de55deefff92ae11 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Wed, 12 Nov 2025 19:40:21 +0100
Subject: [PATCH] Re-arrange OpenAPI Scopes for OAuth2 (#3799)

---
 .changeset/calm-shirts-tie.md                 |  5 +++++
 .../src/OpenAPIRequiredScopes.tsx             | 16 +++++++---------
 .../react-openapi/src/OpenAPISecurities.tsx   | 19 ++++++++++++++++---
 packages/react-openapi/src/translations/de.ts |  1 +
 packages/react-openapi/src/translations/en.ts |  1 +
 packages/react-openapi/src/translations/es.ts |  1 +
 packages/react-openapi/src/translations/fr.ts |  1 +
 packages/react-openapi/src/translations/ja.ts |  1 +
 packages/react-openapi/src/translations/nl.ts |  1 +
 packages/react-openapi/src/translations/no.ts |  1 +
 .../react-openapi/src/translations/pt-br.ts   |  1 +
 packages/react-openapi/src/translations/zh.ts |  1 +
 12 files changed, 37 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/calm-shirts-tie.md

diff --git a/.changeset/calm-shirts-tie.md b/.changeset/calm-shirts-tie.md
new file mode 100644
index 000000000..2ecafaa2e
--- /dev/null
+++ b/.changeset/calm-shirts-tie.md
@@ -0,0 +1,5 @@
+---
+'@gitbook/react-openapi': patch
+---
+
+Re-arrange OpenAPI Scopes for OAuth2
diff --git a/packages/react-openapi/src/OpenAPIRequiredScopes.tsx b/packages/react-openapi/src/OpenAPIRequiredScopes.tsx
index 78436f208..6bef0def0 100644
--- a/packages/react-openapi/src/OpenAPIRequiredScopes.tsx
+++ b/packages/react-openapi/src/OpenAPIRequiredScopes.tsx
@@ -25,12 +25,6 @@ export function OpenAPIRequiredScopes(props: {
     }
 
     const scopes = selectedSecurity.schemes.flatMap((scheme) => {
-        if (scheme.type === 'oauth2') {
-            return Object.entries(scheme.flows ?? {}).flatMap(([_, flow]) =>
-                Object.entries(flow.scopes ?? {})
-            );
-        }
-
         return scheme.scopes ?? [];
     });
 
@@ -66,16 +60,20 @@ export function OpenAPIRequiredScopes(props: {
     );
 }
 
-function OpenAPISchemaScopes(props: {
+export function OpenAPISchemaScopes(props: {
     scopes: OpenAPISecurityScope[];
     context: OpenAPIClientContext;
+    isOAuth2?: boolean;
 }) {
-    const { scopes, context } = props;
+    const { scopes, context, isOAuth2 } = props;
 
     return (
         <div className="openapi-securities-scopes openapi-markdown">
             <div className="openapi-required-scopes-description">
-                {t(context.translation, 'required_scopes_description')}
+                {t(
+                    context.translation,
+                    isOAuth2 ? 'available_scopes' : 'required_scopes_description'
+                )}
             </div>
             <ul>
                 {scopes.map((scope) => (
diff --git a/packages/react-openapi/src/OpenAPISecurities.tsx b/packages/react-openapi/src/OpenAPISecurities.tsx
index d1d00a71e..6a918dad8 100644
--- a/packages/react-openapi/src/OpenAPISecurities.tsx
+++ b/packages/react-openapi/src/OpenAPISecurities.tsx
@@ -3,7 +3,7 @@ import { Fragment } from 'react';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPICopyButton } from './OpenAPICopyButton';
-import { OpenAPIRequiredScopes } from './OpenAPIRequiredScopes';
+import { OpenAPIRequiredScopes, OpenAPISchemaScopes } from './OpenAPIRequiredScopes';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import type { OpenAPIClientContext } from './context';
 import { t } from './translate';
@@ -43,7 +43,11 @@ export function OpenAPISecurities(props: {
                     body: (
                         <div className="openapi-schema">
                             {schemes.map((security, index) => {
-                                const description = resolveDescription(security);
+                                // OAuth2 description is already rendered in OpenAPISchemaOAuth2Item
+                                const description =
+                                    security.type !== 'oauth2'
+                                        ? resolveDescription(security)
+                                        : undefined;
                                 return (
                                     <div
                                         key={`${key}-${index}`}
@@ -172,6 +176,10 @@ function OpenAPISchemaOAuth2Item(props: {
         return null;
     }
 
+    const scopes = !security.scopes?.length && flow.scopes ? Object.entries(flow.scopes) : [];
+
+    const description = resolveDescription(security);
+
     return (
         <div>
             <OpenAPISchemaName
@@ -181,7 +189,9 @@ function OpenAPISchemaOAuth2Item(props: {
                 required={security.required}
             />
             <div className="openapi-securities-oauth-content openapi-markdown">
-                {security.description ? <Markdown source={security.description} /> : null}
+                {description ? (
+                    <Markdown source={description} className="openapi-securities-description" />
+                ) : null}
                 {'authorizationUrl' in flow && flow.authorizationUrl ? (
                     <span>
                         Authorization URL:{' '}
@@ -221,6 +231,9 @@ function OpenAPISchemaOAuth2Item(props: {
                         </OpenAPICopyButton>
                     </span>
                 ) : null}
+                {scopes.length ? (
+                    <OpenAPISchemaScopes scopes={scopes} context={context} isOAuth2 />
+                ) : null}
             </div>
         </div>
     );
diff --git a/packages/react-openapi/src/translations/de.ts b/packages/react-openapi/src/translations/de.ts
index 3e6c559ee..87d30d3d1 100644
--- a/packages/react-openapi/src/translations/de.ts
+++ b/packages/react-openapi/src/translations/de.ts
@@ -38,6 +38,7 @@ export const de = {
     available_items: 'Verfügbare Elemente',
     required_scopes: 'Erforderliche Scopes',
     required_scopes_description: 'Dieser Endpunkt erfordert die folgenden Scopes:',
+    available_scopes: 'Verfügbare Scopes:',
     properties: 'Eigenschaften',
     or: 'oder',
     and: 'und',
diff --git a/packages/react-openapi/src/translations/en.ts b/packages/react-openapi/src/translations/en.ts
index f00ae6df1..3c575f7cd 100644
--- a/packages/react-openapi/src/translations/en.ts
+++ b/packages/react-openapi/src/translations/en.ts
@@ -38,6 +38,7 @@ export const en = {
     available_items: 'Available items',
     required_scopes: 'Required scopes',
     required_scopes_description: 'This endpoint requires the following scopes:',
+    available_scopes: 'Available scopes:',
     possible_values: 'Possible values',
     properties: 'Properties',
     or: 'or',
diff --git a/packages/react-openapi/src/translations/es.ts b/packages/react-openapi/src/translations/es.ts
index d1560dca2..bb4f7372f 100644
--- a/packages/react-openapi/src/translations/es.ts
+++ b/packages/react-openapi/src/translations/es.ts
@@ -38,6 +38,7 @@ export const es = {
     available_items: 'Elementos disponibles',
     required_scopes: 'Scopes requeridos',
     required_scopes_description: 'Este endpoint requiere los siguientes scopes:',
+    available_scopes: 'Scopes disponibles:',
     properties: 'Propiedades',
     or: 'o',
     and: 'y',
diff --git a/packages/react-openapi/src/translations/fr.ts b/packages/react-openapi/src/translations/fr.ts
index cbcb68206..fff5723c3 100644
--- a/packages/react-openapi/src/translations/fr.ts
+++ b/packages/react-openapi/src/translations/fr.ts
@@ -38,6 +38,7 @@ export const fr = {
     available_items: 'Éléments disponibles',
     required_scopes: 'Scopes requis',
     required_scopes_description: 'Cet endpoint nécessite les scopes suivants:',
+    available_scopes: 'Scopes disponibles:',
     properties: 'Propriétés',
     or: 'ou',
     and: 'et',
diff --git a/packages/react-openapi/src/translations/ja.ts b/packages/react-openapi/src/translations/ja.ts
index 70e883c11..cf5f05b70 100644
--- a/packages/react-openapi/src/translations/ja.ts
+++ b/packages/react-openapi/src/translations/ja.ts
@@ -38,6 +38,7 @@ export const ja = {
     available_items: '利用可能なアイテム',
     required_scopes: '必須スコープ',
     required_scopes_description: 'このエンドポイントには次のスコープが必要です：',
+    available_scopes: '利用可能なスコープ：',
     properties: 'プロパティ',
     or: 'または',
     and: 'かつ',
diff --git a/packages/react-openapi/src/translations/nl.ts b/packages/react-openapi/src/translations/nl.ts
index 836eb00d5..ce37c6696 100644
--- a/packages/react-openapi/src/translations/nl.ts
+++ b/packages/react-openapi/src/translations/nl.ts
@@ -38,6 +38,7 @@ export const nl = {
     available_items: 'Beschikbare items',
     required_scopes: 'Vereiste scopes',
     required_scopes_description: 'Dit endpoint vereist de volgende scopes:',
+    available_scopes: 'Beschikbare scopes:',
     properties: 'Eigenschappen',
     or: 'of',
     and: 'en',
diff --git a/packages/react-openapi/src/translations/no.ts b/packages/react-openapi/src/translations/no.ts
index ef6196055..ca42bf6d9 100644
--- a/packages/react-openapi/src/translations/no.ts
+++ b/packages/react-openapi/src/translations/no.ts
@@ -38,6 +38,7 @@ export const no = {
     available_items: 'Tilgjengelige elementer',
     required_scopes: 'Påkrevde scopes',
     required_scopes_description: 'Dette endepunktet krever følgende scopes:',
+    available_scopes: 'Tilgjengelige scopes:',
     properties: 'Egenskaper',
     or: 'eller',
     and: 'og',
diff --git a/packages/react-openapi/src/translations/pt-br.ts b/packages/react-openapi/src/translations/pt-br.ts
index 9b434ace8..c0548180a 100644
--- a/packages/react-openapi/src/translations/pt-br.ts
+++ b/packages/react-openapi/src/translations/pt-br.ts
@@ -38,6 +38,7 @@ export const pt_br = {
     available_items: 'Itens disponíveis',
     required_scopes: 'Scopes obrigatórios',
     required_scopes_description: 'Este endpoint requer os seguintes scopes:',
+    available_scopes: 'Scopes disponíveis:',
     properties: 'Propriedades',
     or: 'ou',
     and: 'e',
diff --git a/packages/react-openapi/src/translations/zh.ts b/packages/react-openapi/src/translations/zh.ts
index 0861095c8..02b7aca59 100644
--- a/packages/react-openapi/src/translations/zh.ts
+++ b/packages/react-openapi/src/translations/zh.ts
@@ -38,6 +38,7 @@ export const zh = {
     available_items: '可用项',
     required_scopes: '必需范围',
     required_scopes_description: '此端点需要以下范围：',
+    available_scopes: '可用范围：',
     properties: '属性',
     or: '或',
     and: '和',