chore(cli): plumb token header and token prefix oAuth (#5207)

* plumb top level roles to FDR * updated changelog * add org id to run preview server * plumbed header key * changed name to token header * chore: update changelog * updated fdr * changelog formatting * chore: update changelog * added example of setting the token-header and prefix, and added note to documentation * chore: update changelog * push fixture test and address comments * chore: update changelog * added yaml example to documentation * fix merge conflicts --------- Co-authored-by: fern-bot <[email protected]> Co-authored-by: fern-bot <[email protected]>
fern-api · Nov 19, 2024 · 6ca385c · 6ca385c
1 parent d71fe3d
commit 6ca385c
Show file tree

Hide file tree

Showing 48 changed files with 492 additions and 60 deletions.
diff --git a/api-yml.schema.json b/api-yml.schema.json
@@ -619,6 +619,16 @@
             }
           ]
         },
+        "token-header": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "get-token": {
           "$ref": "#/definitions/auth.OAuthGetTokenEndpointSchema"
         },

diff --git a/fern.schema.json b/fern.schema.json
@@ -2656,6 +2656,26 @@
               "type": "null"
             }
           ]
+        },
+        "transport": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/service.ServiceTransport"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "source": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/source.SourceSchema"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [

diff --git a/fern/apis/fern-definition/definition/auth.yml b/fern/apis/fern-definition/definition/auth.yml
@@ -85,7 +85,12 @@ types:
       scopes: optional<list<string>>
       client-id-env: optional<string>
       client-secret-env: optional<string>
-      token-prefix: optional<string>
+      token-prefix: 
+        type: optional<string>
+        docs: Sets the token header value prefix. Defaults to 'Bearer'
+      token-header: 
+        type: optional<string>
+        docs: Sets the token header key name. Defaults to 'Authorization'
       get-token: OAuthGetTokenEndpointSchema
       refresh-token: optional<OAuthRefreshTokenEndpointSchema>
 

diff --git a/fern/apis/fern-definition/definition/service.yml b/fern/apis/fern-definition/definition/service.yml
@@ -51,6 +51,8 @@ types:
       errors: optional<ResponseErrorsSchema>
       examples: optional<list<examples.ExampleEndpointCallSchema>>
       pagination: optional<Pagination>
+      transport: optional<ServiceTransport>
+      source: optional<source.SourceSchema>
 
   HttpMethodSchema: 
     enum: 

diff --git a/fern/pages/api-definition/fern-definition/auth.mdx b/fern/pages/api-definition/fern-definition/auth.mdx
@@ -205,4 +205,20 @@ If the `expires-in` property is set, the generated OAuth token provider will aut
 Otherwise, it's assumed that the access token is valid indefinitely.
 
 With this, all of the OAuth logic happens automatically in the generated SDKs. As long as you configure these settings, your
-client will automatically retrieve an access token and refresh it as needed.
+client will automatically retrieve an access token and refresh it as needed.
+
+When using the docs playground, `token-header` and `token-prefix` can optionally be set to customize the header key name and 
+header value prefix, to match the expected format of the API auth scheme.
+
+For example, the following would produce a header `Fern-Authorization: Fern-Bearer <token>`:
+
+```yaml api.yml {5-6}
+auth-schemes:
+  OAuthScheme:
+    scheme: oauth
+    type: client-credentials
+    token-header: Fern-Authorization
+    token-prefix: Fern-Bearer
+    get-token:
+      ...   
+```
diff --git a/generators-yml.schema.json b/generators-yml.schema.json
@@ -386,6 +386,16 @@
             }
           ]
         },
+        "token-header": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "get-token": {
           "$ref": "#/definitions/fernDefinition.auth.OAuthGetTokenEndpointSchema"
         },

diff --git a/package-yml.schema.json b/package-yml.schema.json
@@ -2676,6 +2676,26 @@
               "type": "null"
             }
           ]
+        },
+        "transport": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/service.ServiceTransport"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "source": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/source.SourceSchema"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [

diff --git a/packages/cli/cli/versions.yml b/packages/cli/cli/versions.yml
@@ -1,3 +1,21 @@
+- changelogEntry:
+    - summary: |
+        OAuth Client Credential Auth Scheme now supports the ability to optionally 
+        set token header and prefix fields for use with docs playground.
+
+        ```yml api.yml
+        auth-schemes:
+          OAuth:
+            scheme: oauth
+            type: client-credentials
+            token-header: Fern-Authorization
+            token-prefix: Fern-Bearer
+            ...
+        ```
+      type: feat
+  irVersion: 53
+  version: 0.45.0-rc48
+
 - changelogEntry:
     - summary: |
         Support SDK generation provided comma-delineated content-type values in OpenAPI specs.

diff --git a/packages/cli/configuration/package.json b/packages/cli/configuration/package.json
@@ -32,7 +32,7 @@
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-api/fern-definition-schema": "workspace:*",
-    "@fern-fern/fdr-cjs-sdk": "0.123.0-c32499d0e",
+    "@fern-fern/fdr-cjs-sdk": "0.126.1-444264056",
     "@fern-fern/fiddle-sdk": "0.0.584",
     "@fern-fern/generators-sdk": "0.114.0-5745f9e74",
     "find-up": "^6.3.0",

diff --git a/packages/cli/docs-importers/commons/package.json b/packages/cli/docs-importers/commons/package.json
@@ -31,7 +31,7 @@
     "@fern-api/configuration": "workspace:*",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
-    "@fern-fern/fdr-cjs-sdk": "0.123.0-c32499d0e",
+    "@fern-fern/fdr-cjs-sdk": "0.126.1-444264056",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

diff --git a/packages/cli/docs-importers/mintlify/package.json b/packages/cli/docs-importers/mintlify/package.json
@@ -34,7 +34,7 @@
     "@fern-api/task-context": "workspace:*",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/logger": "workspace:*",
-    "@fern-fern/fdr-cjs-sdk": "0.123.0-c32499d0e",
+    "@fern-fern/fdr-cjs-sdk": "0.126.1-444264056",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {

diff --git a/packages/cli/docs-markdown-utils/package.json b/packages/cli/docs-markdown-utils/package.json
@@ -30,7 +30,7 @@
   "dependencies": {
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
-    "@fern-fern/fdr-cjs-sdk": "0.123.0-c32499d0e",
+    "@fern-fern/fdr-cjs-sdk": "0.126.1-444264056",
     "gray-matter": "^4.0.3",
     "mdast-util-from-markdown": "^2.0.1",
     "mdast-util-mdx": "^3.0.0",

diff --git a/packages/cli/docs-preview/package.json b/packages/cli/docs-preview/package.json
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@fern-api/docs-resolver": "workspace:*",
-    "@fern-api/fdr-sdk": "0.123.0-c32499d0e",
+    "@fern-api/fdr-sdk": "0.126.1-444264056",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",
     "@fern-api/logger": "workspace:*",

diff --git a/packages/cli/docs-preview/src/runPreviewServer.ts b/packages/cli/docs-preview/src/runPreviewServer.ts
@@ -1,5 +1,5 @@
 import { wrapWithHttps } from "@fern-api/docs-resolver";
-import { DocsV1Read, DocsV2Read } from "@fern-api/fdr-sdk";
+import { FernNavigation, DocsV1Read, DocsV2Read } from "@fern-api/fdr-sdk";
 import { dirname, doesPathExist, AbsoluteFilePath } from "@fern-api/fs-utils";
 import { Project } from "@fern-api/project-loader";
 import { TaskContext } from "@fern-api/task-context";
@@ -189,7 +189,8 @@ export async function runPreviewServer({
                     basePath: instance.pathname
                 },
                 definition,
-                lightModeEnabled: definition.config.colorsV3?.type !== "dark"
+                lightModeEnabled: definition.config.colorsV3?.type !== "dark",
+                orgId: FernNavigation.OrgId(initialProject.config.organization)
             };
             res.send(response);
         } catch (error) {

diff --git a/packages/cli/docs-resolver/package.json b/packages/cli/docs-resolver/package.json
@@ -30,8 +30,8 @@
     "@fern-api/configuration": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-markdown-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.123.0-c32499d0e",
-    "@fern-api/ui-core-utils": "0.123.0-c32499d0e",
+    "@fern-api/fdr-sdk": "0.126.1-444264056",
+    "@fern-api/ui-core-utils": "0.126.1-444264056",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",

diff --git a/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts b/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts
@@ -364,7 +364,8 @@ export class DocsDefinitionResolver {
             pointsTo: undefined,
             authed: undefined,
             viewers: undefined,
-            orphaned: undefined
+            orphaned: undefined,
+            roles: this.parsedDocsConfig.roles?.map((role) => FernNavigation.RoleId(role))
         };
     }
 

diff --git a/packages/cli/ete-tests/package.json b/packages/cli/ete-tests/package.json
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@fern-api/configuration": "workspace:*",
-    "@fern-fern/fdr-cjs-sdk": "0.123.0-c32499d0e",
+    "@fern-fern/fdr-cjs-sdk": "0.126.1-444264056",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/logging-execa": "workspace:*",
     "@fern-typescript/fetcher": "workspace:*",

diff --git a/packages/cli/ete-tests/src/tests/docs-dev/docsDev.test.ts b/packages/cli/ete-tests/src/tests/docs-dev/docsDev.test.ts
@@ -30,7 +30,7 @@ describe("fern docs dev", () => {
         const responseBody = JSON.parse(responseText) as FdrCjsSdk.docs.v2.read.LoadDocsForUrlResponse;
         expect(typeof responseBody === "object").toEqual(true);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        expect(Object.keys(responseBody as any)).toEqual(["baseUrl", "definition", "lightModeEnabled"]);
+        expect(Object.keys(responseBody as any)).toEqual(["baseUrl", "definition", "lightModeEnabled", "orgId"]);
 
         // const root = FernNavigation.utils.convertLoadDocsForUrlResponse(responseBody);
         // const pageIds = new Set(Object.keys(responseBody.definition.pages));

diff --git a/...ages/cli/fern-definition/schema/src/schemas/api/resources/auth/types/OAuthSchemeSchema.ts b/...ages/cli/fern-definition/schema/src/schemas/api/resources/auth/types/OAuthSchemeSchema.ts
@@ -10,7 +10,10 @@ export interface OAuthSchemeSchema extends FernDefinition.WithDocsSchema {
     scopes?: string[];
     "client-id-env"?: string;
     "client-secret-env"?: string;
+    /** Sets the token header value prefix. Defaults to 'Bearer' */
     "token-prefix"?: string;
+    /** Sets the token header key name. Defaults to 'Authorization' */
+    "token-header"?: string;
     "get-token": FernDefinition.OAuthGetTokenEndpointSchema;
     "refresh-token"?: FernDefinition.OAuthRefreshTokenEndpointSchema;
 }
diff --git a/...ern-definition/schema/src/schemas/serialization/resources/auth/types/OAuthSchemeSchema.ts b/...ern-definition/schema/src/schemas/serialization/resources/auth/types/OAuthSchemeSchema.ts
@@ -20,6 +20,7 @@ export const OAuthSchemeSchema: core.serialization.ObjectSchema<
         "client-id-env": core.serialization.string().optional(),
         "client-secret-env": core.serialization.string().optional(),
         "token-prefix": core.serialization.string().optional(),
+        "token-header": core.serialization.string().optional(),
         "get-token": OAuthGetTokenEndpointSchema,
         "refresh-token": OAuthRefreshTokenEndpointSchema.optional(),
     })
@@ -33,6 +34,7 @@ export declare namespace OAuthSchemeSchema {
         "client-id-env"?: string | null;
         "client-secret-env"?: string | null;
         "token-prefix"?: string | null;
+        "token-header"?: string | null;
         "get-token": OAuthGetTokenEndpointSchema.Raw;
         "refresh-token"?: OAuthRefreshTokenEndpointSchema.Raw | null;
     }

diff --git a/packages/cli/generation/ir-generator/src/__test__/test-definitions/any-auth.json b/packages/cli/generation/ir-generator/src/__test__/test-definitions/any-auth.json
@@ -95,6 +95,7 @@
                     "clientIdEnvVar": "MY_CLIENT_ID",
                     "clientSecretEnvVar": "MY_CLIENT_SECRET",
                     "tokenPrefix": null,
+                    "tokenHeader": null,
                     "scopes": null,
                     "tokenEndpoint": {
                         "endpointReference": {

diff --git a/...neration/ir-generator/src/__test__/test-definitions/oauth-client-credentials-default.json b/...neration/ir-generator/src/__test__/test-definitions/oauth-client-credentials-default.json
@@ -32,6 +32,7 @@
                     "clientIdEnvVar": null,
                     "clientSecretEnvVar": null,
                     "tokenPrefix": null,
+                    "tokenHeader": null,
                     "scopes": null,
                     "tokenEndpoint": {
                         "endpointReference": {

diff --git a/...nerator/src/__test__/test-definitions/oauth-client-credentials-environment-variables.json b/...nerator/src/__test__/test-definitions/oauth-client-credentials-environment-variables.json
@@ -32,6 +32,7 @@
                     "clientIdEnvVar": "CLIENT_ID",
                     "clientSecretEnvVar": "CLIENT_SECRET",
                     "tokenPrefix": null,
+                    "tokenHeader": null,
                     "scopes": null,
                     "tokenEndpoint": {
                         "endpointReference": {

diff --git a/...tion/ir-generator/src/__test__/test-definitions/oauth-client-credentials-nested-root.json b/...tion/ir-generator/src/__test__/test-definitions/oauth-client-credentials-nested-root.json
@@ -32,6 +32,7 @@
                     "clientIdEnvVar": null,
                     "clientSecretEnvVar": null,
                     "tokenPrefix": null,
+                    "tokenHeader": null,
                     "scopes": null,
                     "tokenEndpoint": {
                         "endpointReference": {

diff --git a/...s/cli/generation/ir-generator/src/__test__/test-definitions/oauth-client-credentials.json b/...s/cli/generation/ir-generator/src/__test__/test-definitions/oauth-client-credentials.json
@@ -32,6 +32,7 @@
                     "clientIdEnvVar": null,
                     "clientSecretEnvVar": null,
                     "tokenPrefix": null,
+                    "tokenHeader": null,
                     "scopes": null,
                     "tokenEndpoint": {
                         "endpointReference": {

diff --git a/packages/cli/generation/ir-generator/src/converters/convertOAuthClientCredentials.ts b/packages/cli/generation/ir-generator/src/converters/convertOAuthClientCredentials.ts
@@ -44,6 +44,7 @@ export async function convertOAuthClientCredentials({
         clientIdEnvVar: oauthScheme["client-id-env"],
         clientSecretEnvVar: oauthScheme["client-secret-env"],
         tokenPrefix: oauthScheme["token-prefix"],
+        tokenHeader: oauthScheme["token-header"],
         scopes: oauthScheme.scopes,
         tokenEndpoint: oauthTokenEndpoint,
         refreshEndpoint

diff --git a/packages/cli/generation/remote-generation/remote-workspace-runner/package.json b/packages/cli/generation/remote-generation/remote-workspace-runner/package.json
@@ -34,7 +34,7 @@
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-resolver": "workspace:*",
     "@fern-api/logging-execa": "workspace:*",
-    "@fern-fern/fdr-cjs-sdk": "0.123.0-c32499d0e",
+    "@fern-fern/fdr-cjs-sdk": "0.126.1-444264056",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-migrations": "workspace:*",

diff --git a/packages/cli/lazy-fern-workspace/src/api-yml.schema.json b/packages/cli/lazy-fern-workspace/src/api-yml.schema.json
@@ -619,6 +619,16 @@
             }
           ]
         },
+        "token-header": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "get-token": {
           "$ref": "#/definitions/auth.OAuthGetTokenEndpointSchema"
         },

diff --git a/packages/cli/lazy-fern-workspace/src/fern.schema.json b/packages/cli/lazy-fern-workspace/src/fern.schema.json
@@ -2656,6 +2656,26 @@
               "type": "null"
             }
           ]
+        },
+        "transport": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/service.ServiceTransport"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "source": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/source.SourceSchema"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [