fix(cli): bump current depth when generating union examples (#4987)

fern-api · Oct 23, 2024 · e3abb3c · e3abb3c
1 parent 5273eae
commit e3abb3c
Show file tree

Hide file tree

Showing 11 changed files with 1,354 additions and 1,188 deletions.
diff --git a/fern/pages/changelogs/cli/2024-10-23.mdx b/fern/pages/changelogs/cli/2024-10-23.mdx
@@ -0,0 +1,26 @@
+## 0.45.0-rc16
+**`(fix):`** The Conjure importer now correctly keys the union subvariant by the property of the discriminant. 
+
+```conjure
+union:
+  discriminant: type
+  union:
+    square: Square
+    circle: Circle
+```
+
+is equal to the following Fern Definition:
+
+```yml fern
+union:
+  discriminant: type
+  types:
+    square: 
+      type: Square
+      key: square
+    circle: 
+      type: Circle
+      key: circle
+```
+
+
diff --git a/packages/cli/api-importers/conjure/conjure-to-fern-tests/__test__/__snapshots__/trace.json b/packages/cli/api-importers/conjure/conjure-to-fern-tests/__test__/__snapshots__/trace.json
diff --git a/packages/cli/api-importers/conjure/conjure-to-fern/src/ConjureImporter.ts b/packages/cli/api-importers/conjure/conjure-to-fern/src/ConjureImporter.ts
@@ -136,7 +136,7 @@ export class ConjureImporter extends APIDefinitionImporter<ConjureImporter.Args>
                         auth: true,
                         path: endpointLocator.path,
                         method: endpointLocator.method,
-                        response: endpointDeclaration.returns
+                        response: endpointDeclaration.returns === "binary" ? "file" : endpointDeclaration.returns
                     };
 
                     const pathParameters: Record<string, RawSchemas.HttpPathParameterSchema> = {};
@@ -165,11 +165,13 @@ export class ConjureImporter extends APIDefinitionImporter<ConjureImporter.Args>
                             continue;
                         }
                         if (typeof argDeclaration === "string") {
-                            endpoint.request = { body: { type: argDeclaration } };
+                            endpoint.request = { body: argDeclaration === "binary" ? "bytes" : argDeclaration };
                         } else {
                             switch (argDeclaration.paramType) {
                                 case "body":
-                                    endpoint.request = { body: { type: argDeclaration.type } };
+                                    endpoint.request = {
+                                        body: argDeclaration.type === "binary" ? "bytes" : argDeclaration.type
+                                    };
                                     break;
                                 case "query": {
                                     if (endpoint.request == null) {
@@ -246,18 +248,20 @@ export class ConjureImporter extends APIDefinitionImporter<ConjureImporter.Args>
                 union: (value) => {
                     this.fernDefinitionBuilder.addType(fernFilePath, {
                         name: typeName,
-                        schema: Object.fromEntries(
-                            Object.entries(value.union).map(([key, type]) => {
-                                return [
-                                    key,
-                                    {
-                                        type: typeof type === "string" ? type : type.type,
-                                        docs: typeof type === "string" ? undefined : type.docs,
-                                        key
-                                    }
-                                ];
-                            })
-                        )
+                        schema: {
+                            union: Object.fromEntries(
+                                Object.entries(value.union).map(([key, type]) => {
+                                    return [
+                                        key,
+                                        {
+                                            type: typeof type === "string" ? type : type.type,
+                                            docs: typeof type === "string" ? undefined : type.docs,
+                                            key
+                                        }
+                                    ];
+                                })
+                            )
+                        }
                     });
                 }
             });

diff --git a/packages/cli/api-importers/conjure/conjure-to-fern/src/utils/listConjureFiles.ts b/packages/cli/api-importers/conjure/conjure-to-fern/src/utils/listConjureFiles.ts
@@ -39,7 +39,6 @@ async function createConjureFile({
         .replaceAll(": safelong", ": long")
         .replaceAll("<safelong>", "<long>")
         .replaceAll("safelong>", "long>")
-        .replaceAll(": binary", ": file")
         .replaceAll(": any", ": unknown")
         .replaceAll("<any>", "<unknown>")
         .replaceAll("any>", "unknown>");

diff --git a/packages/cli/cli/versions.yml b/packages/cli/cli/versions.yml
@@ -1,3 +1,12 @@
+- changelogEntry:
+    - summary: | 
+        - Improved union example generation by increasing depth for better handling of recursive structures.
+        - Updated Conjure importer to represent binary types as bytes for requests and file for responses in Fern.
+        - Added detailed error messages when 'fern docs dev' fails, accessible with --log-level debug.
+      type: fix
+  irVersion: 53
+  version: 0.45.0-rc17
+
 - changelogEntry:
     - summary: |
         The Conjure importer now correctly keys the union subvariant by the property of the discriminant. 

diff --git a/packages/cli/docs-preview/src/runPreviewServer.ts b/packages/cli/docs-preview/src/runPreviewServer.ts
@@ -140,6 +140,11 @@ export async function runPreviewServer({
             } else {
                 context.logger.error("Failed to read docs configuration. Rendering last successful configuration.");
             }
+            if (err instanceof Error) {
+                if (err instanceof Error && err.stack) {
+                    context.logger.debug(`${err.message}\n${err.stack}`);
+                }
+            }
             return docsDefinition;
         }
     };

diff --git a/.../fern-definition/validator/src/rules/no-duplicate-field-names/no-duplicate-field-names.ts b/.../fern-definition/validator/src/rules/no-duplicate-field-names/no-duplicate-field-names.ts
@@ -95,6 +95,12 @@ export const NoDuplicateFieldNamesRule: Rule = {
                                         ? singleUnionType.type
                                         : undefined;
 
+                                // if the union type has a key, we don't need to check for conflicts
+                                // because the variant is nested under the key
+                                if (typeof singleUnionType === "object" && singleUnionType.key != null) {
+                                    continue;
+                                }
+
                                 if (specifiedType != null) {
                                     const resolvedType = typeResolver.resolveType({
                                         type: specifiedType,

diff --git a/...ages/cli/generation/ir-generator/src/examples/generator/generateTypeDeclarationExample.ts b/...ages/cli/generation/ir-generator/src/examples/generator/generateTypeDeclarationExample.ts
@@ -178,7 +178,7 @@ export function generateTypeDeclarationExample({
                     },
                     singleProperty: (value) => {
                         const singlePropertyExample = generateTypeReferenceExample({
-                            currentDepth,
+                            currentDepth: currentDepth + 1,
                             maxDepth,
                             fieldName,
                             typeReference: value.type,

diff --git a/packages/cli/generation/ir-generator/src/index.ts b/packages/cli/generation/ir-generator/src/index.ts
@@ -35,3 +35,4 @@ export { parseReferenceToEndpointName, type ReferenceToEndpointName } from "./ut
 export { parseReferenceToTypeName, type ReferenceToTypeName } from "./utils/parseReferenceToTypeName";
 export { IdGenerator } from "./IdGenerator";
 export { convertToFernFilepath } from "./utils/convertToFernFilepath";
+export { generateEndpointExample } from "./examples/generator/generateSuccessEndpointExample";
diff --git a/packages/cli/register/src/ir-to-fdr-converter/__test__/__snapshots__/file-download.json b/packages/cli/register/src/ir-to-fdr-converter/__test__/__snapshots__/file-download.json
@@ -32,7 +32,20 @@
             }
           },
           "errorsV2": [],
-          "examples": []
+          "examples": [
+            {
+              "path": "",
+              "pathParameters": {},
+              "queryParameters": {},
+              "headers": {},
+              "responseStatusCode": 204,
+              "responseBodyV3": {
+                "type": "filename",
+                "value": "<bytes>"
+              },
+              "codeSamples": []
+            }
+          ]
         }
       ],
       "webhooks": [],

diff --git a/packages/cli/register/src/ir-to-fdr-converter/convertPackage.ts b/packages/cli/register/src/ir-to-fdr-converter/convertPackage.ts
@@ -1,4 +1,5 @@
 import { assertNever, isNonNullish, isPlainObject, MediaType } from "@fern-api/core-utils";
+import { generateEndpointExample } from "@fern-api/ir-generator";
 import {
     AutogeneratedEndpointExample,
     ExampleCodeSample,
@@ -68,7 +69,7 @@ function convertService(
     const endpoints: FdrCjsSdk.api.v1.register.EndpointDefinition[] = [];
     for (const irEndpoint of irService.endpoints) {
         const autogeneratedExample = irEndpoint.autogeneratedExamples[0];
-        const examples = [];
+        const examples: FdrCjsSdk.api.v1.register.ExampleEndpointCall[] = [];
         if (irEndpoint.userSpecifiedExamples.length > 0 && autogeneratedExample != null) {
             examples.push(
                 ...irEndpoint.userSpecifiedExamples.map((userSpecifiedExample) =>
@@ -88,6 +89,26 @@ function convertService(
                     ir
                 })
             );
+        } else if (irEndpoint.response?.body?.type === "fileDownload") {
+            const example = generateEndpointExample({
+                ir,
+                service: irService,
+                endpoint: { ...irEndpoint, response: undefined },
+                typeDeclarations: ir.types,
+                skipOptionalRequestProperties: true,
+                generationResponse: { type: "success" }
+            });
+            if (example.type === "success") {
+                const convertedExample: FdrCjsSdk.api.v1.register.ExampleEndpointCall = {
+                    ...convertHttpEndpointExample({
+                        autogeneratedExample: example,
+                        irEndpoint,
+                        ir
+                    }),
+                    responseBodyV3: { type: "filename", value: "<bytes>" }
+                };
+                examples.push(convertedExample);
+            }
         }
         const endpoint = {
             availability: convertIrAvailability(irEndpoint.availability ?? irService.availability),