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

…5255) * fix(cli): docs generation now preserves original model schema names. * chore: update changelog * Add test cases & refine `getSchemaName`. * Update versions.yml. --------- Co-authored-by: eyw520 <eyw520@users.noreply.github.com>
fern-api · Nov 22, 2024 · bcc0a17 · bcc0a17
1 parent a3a4c2f
commit bcc0a17
Show file tree

Hide file tree

Showing 28 changed files with 43,312 additions and 32 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,24 @@
 import { camelCase, upperFirst } from "lodash-es";
 import { replaceStartingNumber } from "./replaceStartingNumber";
 
-export function getGeneratedTypeName(breadcrumbs: string[]): string {
-    const underscoreDelimeted = breadcrumbs.join("_");
-    const name = upperFirst(camelCase(underscoreDelimeted));
+export function getGeneratedTypeName(breadcrumbs: string[], useOriginalSchemaIds: boolean): string {
+    const processedTokens = breadcrumbs.map((token) => {
+        if (/^[^a-zA-Z0-9]+$/.test(token)) {
+            return token;
+        } else {
+            return upperFirst(camelCase(token));
+        }
+    });
+
+    const name = processedTokens.join("");
+
     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);
 }