fix(cli): docs generation now preserves original model schema names.

fern-api · Nov 22, 2024 · b9e968a · b9e968a
1 parent d594089
commit b9e968a
Show file tree

Hide file tree

Showing 18 changed files with 87 additions and 30 deletions.
diff --git a/...porters/openapi/openapi-ir-parser/src/openapi/v3/converters/endpoint/convertParameters.ts b/...porters/openapi/openapi-ir-parser/src/openapi/v3/converters/endpoint/convertParameters.ts
@@ -63,7 +63,7 @@ export function convertParameters({
         const availability = convertAvailability(resolvedParameter);
 
         const parameterBreadcrumbs = [...requestBreadcrumbs, resolvedParameter.name];
-        const generatedName = getGeneratedTypeName(parameterBreadcrumbs);
+        const generatedName = getGeneratedTypeName(parameterBreadcrumbs, context.options.preserveSchemaIds);
 
         let schema =
             resolvedParameter.schema != null

diff --git a/...penapi/openapi-ir-parser/src/openapi/v3/converters/operation/convertAsyncSyncOperation.ts b/...penapi/openapi-ir-parser/src/openapi/v3/converters/operation/convertAsyncSyncOperation.ts
@@ -69,7 +69,7 @@ export function convertAsyncSyncOperation({
         name: headerToIgnore,
         schema: SchemaWithExample.literal({
             nameOverride: undefined,
-            generatedName: getGeneratedTypeName([headerToIgnore]),
+            generatedName: getGeneratedTypeName([headerToIgnore], context.options.preserveSchemaIds),
             title: undefined,
             description: undefined,
             availability: undefined,

diff --git a/...ers/openapi/openapi-ir-parser/src/openapi/v3/converters/operation/convertHttpOperation.ts b/...ers/openapi/openapi-ir-parser/src/openapi/v3/converters/operation/convertHttpOperation.ts
@@ -121,7 +121,7 @@ export function convertHttpOperation({
         queryParameters: convertedParameters.queryParameters,
         headers: convertedParameters.headers,
         requestNameOverride: requestNameOverride ?? undefined,
-        generatedRequestName: getGeneratedTypeName(requestBreadcrumbs),
+        generatedRequestName: getGeneratedTypeName(requestBreadcrumbs, context.options.preserveSchemaIds),
         request: convertedRequest,
         response: convertedResponse.value,
         errors: convertedResponse.errors,

diff --git a/.../openapi/openapi-ir-parser/src/openapi/v3/converters/operation/convertWebhookOperation.ts b/.../openapi/openapi-ir-parser/src/openapi/v3/converters/operation/convertWebhookOperation.ts
@@ -64,7 +64,7 @@ export function convertWebhookOperation({
         operationId: operation.operationId,
         tags: context.resolveTagsToTagIds(operation.tags),
         headers: convertedParameters.headers,
-        generatedPayloadName: getGeneratedTypeName(payloadBreadcrumbs),
+        generatedPayloadName: getGeneratedTypeName(payloadBreadcrumbs, context.options.preserveSchemaIds),
         payload: convertedPayload.schema,
         description: operation.description,
         examples: convertWebhookExamples(convertedPayload.fullExamples),

diff --git a/...i-importers/openapi/openapi-ir-parser/src/openapi/v3/extensions/getVariableDefinitions.ts b/...i-importers/openapi/openapi-ir-parser/src/openapi/v3/extensions/getVariableDefinitions.ts
@@ -5,7 +5,10 @@ import { getDefaultAsString } from "../../../schema/defaults/getDefault";
 import { getGeneratedTypeName } from "../../../schema/utils/getSchemaName";
 import { FernOpenAPIExtension } from "./fernExtensions";
 
-export function getVariableDefinitions(document: OpenAPIV3.Document): Record<string, PrimitiveSchema> {
+export function getVariableDefinitions(
+    document: OpenAPIV3.Document,
+    preserveSchemaIds: boolean
+): Record<string, PrimitiveSchema> {
     const variables = getExtension<Record<string, OpenAPIV3.SchemaObject>>(
         document,
         FernOpenAPIExtension.SDK_VARIABLES
@@ -22,7 +25,7 @@ export function getVariableDefinitions(document: OpenAPIV3.Document): Record<str
                     variableName,
                     {
                         nameOverride: undefined,
-                        generatedName: getGeneratedTypeName([variableName]),
+                        generatedName: getGeneratedTypeName([variableName], preserveSchemaIds),
                         title: schema.title,
                         schema: PrimitiveSchemaValue.string({
                             default: getDefaultAsString(schema),

diff --git a/packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/generateIr.ts b/packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/generateIr.ts
@@ -91,7 +91,7 @@ export function generateIr({
         source,
         namespace
     });
-    const variables = getVariableDefinitions(openApi);
+    const variables = getVariableDefinitions(openApi, options.preserveSchemaIds);
     const globalHeaders = getGlobalHeaders(openApi);
     const idempotencyHeaders = getIdempotencyHeaders(openApi);
 
@@ -465,7 +465,10 @@ function maybeAddBackDiscriminantsFromSchemas(
                         ...property,
                         schema: SchemaWithExample.literal({
                             nameOverride: undefined,
-                            generatedName: getGeneratedTypeName([schema.generatedName, discriminantValue]),
+                            generatedName: getGeneratedTypeName(
+                                [schema.generatedName, discriminantValue],
+                                context.options.preserveSchemaIds
+                            ),
                             title: undefined,
                             value: LiteralSchemaValue.string(discriminantValue),
                             groupName: undefined,

diff --git a/packages/cli/api-importers/openapi/openapi-ir-parser/src/options.ts b/packages/cli/api-importers/openapi/openapi-ir-parser/src/options.ts
@@ -19,6 +19,8 @@ export interface ParseOpenAPIOptions {
     onlyIncludeReferencedSchemas: boolean;
     /* Whether or not to include path parameters in the in-lined request */
     inlinePathParameters: boolean;
+    /* Whether or not to preserve original schema Ids in the IR */
+    preserveSchemaIds: boolean;
 }
 
 export const DEFAULT_PARSE_OPENAPI_SETTINGS: ParseOpenAPIOptions = {
@@ -30,5 +32,6 @@ export const DEFAULT_PARSE_OPENAPI_SETTINGS: ParseOpenAPIOptions = {
     cooerceEnumsToLiterals: true,
     respectReadonlySchemas: false,
     onlyIncludeReferencedSchemas: false,
-    inlinePathParameters: false
+    inlinePathParameters: false,
+    preserveSchemaIds: false
 };
diff --git a/packages/cli/api-importers/openapi/openapi-ir-parser/src/parse.ts b/packages/cli/api-importers/openapi/openapi-ir-parser/src/parse.ts
@@ -206,7 +206,8 @@ function getParseOptions({
         inlinePathParameters:
             overrides?.inlinePathParameters ??
             specSettings?.inlinePathParameters ??
-            DEFAULT_PARSE_OPENAPI_SETTINGS.inlinePathParameters
+            DEFAULT_PARSE_OPENAPI_SETTINGS.inlinePathParameters,
+        preserveSchemaIds: overrides?.preserveSchemaIds ?? DEFAULT_PARSE_OPENAPI_SETTINGS.preserveSchemaIds
     };
 }
 

diff --git a/packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertObject.ts b/packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertObject.ts
@@ -127,7 +127,12 @@ export function convertObject({
             }
             parents.push({
                 schemaId,
-                convertedSchema: convertToReferencedSchema(allOfElement, [schemaId], source),
+                convertedSchema: convertToReferencedSchema(
+                    allOfElement,
+                    [schemaId],
+                    source,
+                    context.options.preserveSchemaIds
+                ),
                 properties: getAllProperties({ schema: allOfElement, context, breadcrumbs, source, namespace })
             });
             context.markSchemaAsReferencedByNonRequest(schemaId);

diff --git a/packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertSchemas.ts b/packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertSchemas.ts
@@ -115,12 +115,14 @@ export function convertReferenceObject(
               namespace,
               new Set()
           )
-        : SchemaWithExample.reference(convertToReferencedSchema(schema, breadcrumbs, source));
+        : SchemaWithExample.reference(
+              convertToReferencedSchema(schema, breadcrumbs, source, context.options.preserveSchemaIds)
+          );
     if (wrapAsNullable) {
         return SchemaWithExample.nullable({
             title: undefined,
             nameOverride: undefined,
-            generatedName: getGeneratedTypeName(breadcrumbs),
+            generatedName: getGeneratedTypeName(breadcrumbs, context.options.preserveSchemaIds),
             value: referenceSchema,
             description: undefined,
             availability: undefined,
@@ -166,7 +168,7 @@ export function convertSchemaObject(
     let groupName: SdkGroupName = (typeof mixedGroupName === "string" ? [mixedGroupName] : mixedGroupName) ?? [];
     groupName = context.resolveGroupName(groupName);
 
-    const generatedName = getGeneratedTypeName(breadcrumbs);
+    const generatedName = getGeneratedTypeName(breadcrumbs, context.options.preserveSchemaIds);
     const title = schema.title;
     const description = schema.description;
     const availability = convertAvailability(schema);
@@ -935,10 +937,11 @@ export function getSchemaIdFromReference(ref: OpenAPIV3.ReferenceObject): string
 export function convertToReferencedSchema(
     schema: OpenAPIV3.ReferenceObject,
     breadcrumbs: string[],
-    source: Source
+    source: Source,
+    preserveSchemaIds: boolean
 ): ReferencedSchema {
     const nameOverride = getExtension<string>(schema, FernOpenAPIExtension.TYPE_NAME);
-    const generatedName = getGeneratedTypeName(breadcrumbs);
+    const generatedName = getGeneratedTypeName(breadcrumbs, preserveSchemaIds);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const description = (schema as any).description;
     const availability = convertAvailability(schema);

diff --git a/...ges/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertUndiscriminatedOneOf.ts b/...ges/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertUndiscriminatedOneOf.ts
@@ -66,7 +66,7 @@ export function convertUndiscriminatedOneOf({
             return schema.enum.map((enumValue) => {
                 return SchemaWithExample.literal({
                     nameOverride: undefined,
-                    generatedName: getGeneratedTypeName([generatedName, enumValue]),
+                    generatedName: getGeneratedTypeName([generatedName, enumValue], context.options.preserveSchemaIds),
                     title: undefined,
                     value: LiteralSchemaValue.string(enumValue),
                     groupName: undefined,
@@ -201,7 +201,10 @@ export function convertUndiscriminatedOneOfWithDiscriminant({
             subtypeReference.properties = {
                 [discriminator.propertyName]: SchemaWithExample.literal({
                     nameOverride: undefined,
-                    generatedName: getGeneratedTypeName([generatedName, discriminantValue]),
+                    generatedName: getGeneratedTypeName(
+                        [generatedName, discriminantValue],
+                        context.options.preserveSchemaIds
+                    ),
                     title: undefined,
                     value: LiteralSchemaValue.string(discriminantValue),
                     groupName: undefined,

diff --git a/packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/utils/getSchemaName.ts b/packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/utils/getSchemaName.ts
@@ -1,16 +1,28 @@
-import { camelCase, upperFirst } from "lodash-es";
+import { camelCase, upperFirst, lowerFirst } from "lodash-es";
 import { replaceStartingNumber } from "./replaceStartingNumber";
 
-export function getGeneratedTypeName(breadcrumbs: string[]): string {
-    const underscoreDelimeted = breadcrumbs.join("_");
-    const name = upperFirst(camelCase(underscoreDelimeted));
+function customCamelCase(input: string): string {
+    const tokens = input.split("_");
+    const processedTokens = tokens.map((token, index) => {
+        if (/^[a-zA-Z0-9]+$/.test(token)) {
+            return index === 0 ? lowerFirst(token) : upperFirst(token);
+        }
+        return token;
+    });
+    return processedTokens.join("");
+}
+
+export function getGeneratedTypeName(breadcrumbs: string[], useOriginalSchemaIds: boolean): string {
+    const camelCaseFn = useOriginalSchemaIds ? customCamelCase : camelCase;
+    const underscoreDelimited = breadcrumbs.join("_");
+    const name = upperFirst(camelCaseFn(underscoreDelimited));
     if (/^\d/.test(name)) {
         return replaceStartingNumber(name) ?? name;
     }
     return name;
 }
 
 export function getGeneratedPropertyName(breadcrumbs: string[]): string {
-    const underscoreDelimeted = breadcrumbs.join("_");
-    return camelCase(underscoreDelimeted);
+    const underscoreDelimited = breadcrumbs.join("_");
+    return camelCase(underscoreDelimited);
 }
diff --git a/packages/cli/cli/src/cli.ts b/packages/cli/cli/src/cli.ts
@@ -929,19 +929,26 @@ function addWriteDefinitionCommand(cli: Argv<GlobalCliOptions>, cliContext: CliC
                 .option("language", {
                     choices: Object.values(generatorsYml.GenerationLanguage),
                     description: "Write the definition for a particular SDK language"
+                })
+                .option("preserve-schemas", {
+                    string: true,
+                    description: "Preserve potentially unsafe schema Ids in the generated fern definition"
                 }),
         async (argv) => {
+            const preserveSchemaIds = argv.preserveSchemas != null;
             await cliContext.instrumentPostHogEvent({
                 command: "fern write-definition"
             });
             await writeDefinitionForWorkspaces({
                 project: await loadProjectAndRegisterWorkspacesWithContext(cliContext, {
                     commandLineApiWorkspace: argv.api,
                     defaultToAllApiWorkspaces: true,
-                    sdkLanguage: argv.language
+                    sdkLanguage: argv.language,
+                    preserveSchemaIds
                 }),
                 cliContext,
-                sdkLanguage: argv.language
+                sdkLanguage: argv.language,
+                preserveSchemaIds
             });
         }
     );

diff --git a/packages/cli/cli/src/commands/generate/generateDocsWorkspace.ts b/packages/cli/cli/src/commands/generate/generateDocsWorkspace.ts
@@ -52,7 +52,7 @@ export async function generateDocsWorkspace({
             project.apiWorkspaces.map(async (workspace) => {
                 return workspace.toFernWorkspace(
                     { context },
-                    { enableUniqueErrorsPerEndpoint: true, detectGlobalHeaders: false }
+                    { enableUniqueErrorsPerEndpoint: true, detectGlobalHeaders: false, preserveSchemaIds: true }
                 );
             })
         );

diff --git a/packages/cli/cli/src/commands/write-definition/writeDefinitionForWorkspaces.ts b/packages/cli/cli/src/commands/write-definition/writeDefinitionForWorkspaces.ts
@@ -13,11 +13,13 @@ import { CliContext } from "../../cli-context/CliContext";
 export async function writeDefinitionForWorkspaces({
     project,
     cliContext,
-    sdkLanguage
+    sdkLanguage,
+    preserveSchemaIds
 }: {
     project: Project;
     cliContext: CliContext;
     sdkLanguage: generatorsYml.GenerationLanguage | undefined;
+    preserveSchemaIds: boolean;
 }): Promise<void> {
     await Promise.all(
         project.apiWorkspaces.map(async (workspace) => {
@@ -26,7 +28,7 @@ export async function writeDefinitionForWorkspaces({
                     await writeDefinitionForFernWorkspace({ workspace, context });
                 } else {
                     await writeDefinitionForNonFernWorkspace({
-                        workspace: await workspace.toFernWorkspace({ context }),
+                        workspace: await workspace.toFernWorkspace({ context }, { preserveSchemaIds }),
                         context
                     });
                 }

diff --git a/packages/cli/cli/versions.yml b/packages/cli/cli/versions.yml
@@ -1,3 +1,10 @@
+- changelogEntry:
+    - summary: |
+        Docs generation now preserves original model schema names.
+      type: fix
+  irVersion: 53
+  version: 0.45.0-rc54
+
 - changelogEntry:
     - summary: |
         Add support for the `smart-casing` flags in the IR commands.

diff --git a/packages/cli/lazy-fern-workspace/src/OSSWorkspace.ts b/packages/cli/lazy-fern-workspace/src/OSSWorkspace.ts
@@ -104,9 +104,13 @@ export declare namespace OSSWorkspace {
          */
         cooerceEnumsToLiterals?: boolean;
         /*
-         * Whehter or not to parse object query parameters.
+         * Whether or not to parse object query parameters.
          */
         objectQueryParameters?: boolean;
+        /*
+         * Whether or not to preserve original schema ids.
+         */
+        preserveSchemaIds?: boolean;
     }
 }
 
@@ -302,5 +306,8 @@ function getOptionsOverridesFromSettings(settings?: OSSWorkspace.Settings): Part
     if (settings.cooerceEnumsToLiterals) {
         result.cooerceEnumsToLiterals = true;
     }
+    if (settings.preserveSchemaIds) {
+        result.preserveSchemaIds = true;
+    }
     return result;
 }
diff --git a/packages/cli/project-loader/src/loadProject.ts b/packages/cli/project-loader/src/loadProject.ts
@@ -30,6 +30,7 @@ export declare namespace loadProject {
         context: TaskContext;
         nameOverride?: string;
         sdkLanguage?: generatorsYml.GenerationLanguage;
+        preserveSchemaIds?: boolean;
     }
 
     export interface LoadProjectFromDirectoryArgs extends Args {