Add referenced examples with $ (#1066)

* Handle $ in examples when generating IR

* Fix fern check rules

* Add no-duplicate-example-names rule

* Add no-undefined-example-reference rule

* Update docs with example references

* Fix IR tests

* Support \$

packages/cli/ete-tests/src/tests/ir/fixtures/simple/fern/api/definition/director.yml

@@ -3,6 +3,14 @@ types:
     properties:
       name: string
       age: Age
+    examples:
+      - name: GeorgeExample
+        value:
+          name: George the Director
+          age: $Age.Example1
   Age:
     type: integer
+    examples:
+      - name: Example1
+        value: 20
   LiteralString: literal<"hello">

packages/cli/ete-tests/src/tests/ir/fixtures/simple/fern/api/definition/imdb.yml

@@ -1,6 +1,10 @@
 imports:
   director: director.yml
 types:
+  CurrencyAmount:
+    type: string
+    examples:
+      - value: \$4.50
   MovieId:
     type: string
     examples:
@@ -21,6 +25,17 @@ types:
     properties:
       title: string
       ratings: list<double>
+    examples:
+      - name: Example1
+        value:
+          title: Winnie the Pooh
+          ratings: [1, 2, 3]
+  DirectorWrapper:
+    properties:
+      director: director.Director
+    examples:
+      - value:
+          director: $director.Director.GeorgeExample
   Person:
     union:
       actor: ActorId
@@ -80,6 +95,9 @@ services:
                 ratings: [10, 10, 10, 10]
               response:
                 body: shrek-123
+            - request: $CreateMovieRequest.Example1
+              response:
+                body: shrek-123
         getMovie:
           method: GET
           display-name: "Get Movie by Id"

packages/cli/generation/ir-generator/src/converters/services/convertExampleEndpointCall.ts

@@ -10,6 +10,7 @@ import {
 } from "@fern-fern/ir-model/services/http";
 import { FernFileContext } from "../../FernFileContext";
 import { ErrorResolver } from "../../resolvers/ErrorResolver";
+import { ExampleResolver } from "../../resolvers/ExampleResolver";
 import { TypeResolver } from "../../resolvers/TypeResolver";
 import { parseTypeName } from "../../utils/parseTypeName";
 import {
@@ -23,20 +24,22 @@ export function convertExampleEndpointCall({
     example,
     typeResolver,
     errorResolver,
+    exampleResolver,
     file,
 }: {
     service: RawSchemas.HttpServiceSchema;
     endpoint: RawSchemas.HttpEndpointSchema;
     example: RawSchemas.ExampleEndpointCallSchema;
     typeResolver: TypeResolver;
     errorResolver: ErrorResolver;
+    exampleResolver: ExampleResolver;
     file: FernFileContext;
 }): ExampleEndpointCall {
     return {
         name: example.name,
         docs: example.docs,
-        ...convertPathParameters({ service, endpoint, example, typeResolver, file }),
-        ...convertHeaders({ service, endpoint, example, typeResolver, file }),
+        ...convertPathParameters({ service, endpoint, example, typeResolver, exampleResolver, file }),
+        ...convertHeaders({ service, endpoint, example, typeResolver, exampleResolver, file }),
         queryParameters:
             example["query-parameters"] != null
                 ? Object.entries(example["query-parameters"]).map(([wireKey, value]) => {
@@ -56,13 +59,14 @@ export function convertExampleEndpointCall({
                                       ? queryParameterDeclaration
                                       : queryParameterDeclaration.type,
                               typeResolver,
+                              exampleResolver,
                               file,
                           }),
                       };
                   })
                 : [],
-        request: convertExampleRequestBody({ endpoint, example, typeResolver, file }),
-        response: convertExampleResponse({ endpoint, example, typeResolver, errorResolver, file }),
+        request: convertExampleRequestBody({ endpoint, example, typeResolver, exampleResolver, file }),
+        response: convertExampleResponse({ endpoint, example, typeResolver, errorResolver, exampleResolver, file }),
     };
 }
 
@@ -71,12 +75,14 @@ function convertPathParameters({
     endpoint,
     example,
     typeResolver,
+    exampleResolver,
     file,
 }: {
     service: RawSchemas.HttpServiceSchema;
     endpoint: RawSchemas.HttpEndpointSchema;
     example: RawSchemas.ExampleEndpointCallSchema;
     typeResolver: TypeResolver;
+    exampleResolver: ExampleResolver;
     file: FernFileContext;
 }): Pick<ExampleEndpointCall, "endpointPathParameters" | "servicePathParameters"> {
     const servicePathParameters: ExamplePathParameter[] = [];
@@ -96,6 +102,7 @@ function convertPathParameters({
                                 ? endpointPathParameterDeclaration
                                 : endpointPathParameterDeclaration.type,
                         typeResolver,
+                        exampleResolver,
                         file,
                     }),
                 });
@@ -109,6 +116,7 @@ function convertPathParameters({
                                 ? servicePathParameterDeclaration
                                 : servicePathParameterDeclaration.type,
                         typeResolver,
+                        exampleResolver,
                         file,
                     }),
                 });
@@ -129,12 +137,14 @@ function convertHeaders({
     endpoint,
     example,
     typeResolver,
+    exampleResolver,
     file,
 }: {
     service: RawSchemas.HttpServiceSchema;
     endpoint: RawSchemas.HttpEndpointSchema;
     example: RawSchemas.ExampleEndpointCallSchema;
     typeResolver: TypeResolver;
+    exampleResolver: ExampleResolver;
     file: FernFileContext;
 }): Pick<ExampleEndpointCall, "endpointHeaders" | "serviceHeaders"> {
     const serviceHeaders: ExampleHeader[] = [];
@@ -155,6 +165,7 @@ function convertHeaders({
                                 ? endpointHeaderDeclaration
                                 : endpointHeaderDeclaration.type,
                         typeResolver,
+                        exampleResolver,
                         file,
                     }),
                 });
@@ -168,6 +179,7 @@ function convertHeaders({
                                 ? serviceHeaderDeclaration
                                 : serviceHeaderDeclaration.type,
                         typeResolver,
+                        exampleResolver,
                         file,
                     }),
                 });
@@ -187,11 +199,13 @@ function convertExampleRequestBody({
     endpoint,
     example,
     typeResolver,
+    exampleResolver,
     file,
 }: {
     endpoint: RawSchemas.HttpEndpointSchema;
     example: RawSchemas.ExampleEndpointCallSchema;
     typeResolver: TypeResolver;
+    exampleResolver: ExampleResolver;
     file: FernFileContext;
 }): ExampleRequestBody | undefined {
     const requestType = typeof endpoint.request !== "string" ? endpoint.request?.body : endpoint.request;
@@ -204,6 +218,7 @@ function convertExampleRequestBody({
                 example: example.request,
                 rawTypeBeingExemplified: typeof requestType !== "string" ? requestType.type : requestType,
                 typeResolver,
+                exampleResolver,
                 file,
             })
         );
@@ -226,6 +241,7 @@ function convertExampleRequestBody({
                             ? inlinedRequestPropertyDeclaration.type
                             : inlinedRequestPropertyDeclaration,
                     typeResolver,
+                    exampleResolver,
                     file,
                 }),
                 originalTypeDeclaration: undefined,
@@ -249,6 +265,7 @@ function convertExampleRequestBody({
                             ? originalTypeDeclaration.rawPropertyType
                             : originalTypeDeclaration.rawPropertyType.type,
                     typeResolver,
+                    exampleResolver,
                     file,
                 }),
                 originalTypeDeclaration: originalTypeDeclaration.typeName,
@@ -257,7 +274,8 @@ function convertExampleRequestBody({
     }
 
     return ExampleRequestBody.inlinedRequestBody({
-        jsonExample: example.request,
+        jsonExample: exampleResolver.resolveAllReferencesInExampleOrThrow({ example: example.request, file })
+            .resolvedExample,
         properties: exampleProperties,
     });
 }
@@ -267,12 +285,14 @@ function convertExampleResponse({
     example,
     typeResolver,
     errorResolver,
+    exampleResolver,
     file,
 }: {
     endpoint: RawSchemas.HttpEndpointSchema;
     example: RawSchemas.ExampleEndpointCallSchema;
     typeResolver: TypeResolver;
     errorResolver: ErrorResolver;
+    exampleResolver: ExampleResolver;
     file: FernFileContext;
 }): ExampleResponse {
     if (example.response?.error != null) {
@@ -288,26 +308,29 @@ function convertExampleResponse({
                           example: example.response.body,
                           rawTypeBeingExemplified: errorDeclaration.declaration.type,
                           typeResolver,
+                          exampleResolver,
                           file: errorDeclaration.file,
                       })
                     : undefined,
         });
     }
 
     return ExampleResponse.ok({
-        body: convertExampleResponseBody({ endpoint, example, typeResolver, file }),
+        body: convertExampleResponseBody({ endpoint, example, typeResolver, exampleResolver, file }),
     });
 }
 
 function convertExampleResponseBody({
     endpoint,
     example,
     typeResolver,
+    exampleResolver,
     file,
 }: {
     endpoint: RawSchemas.HttpEndpointSchema;
     example: RawSchemas.ExampleEndpointCallSchema;
     typeResolver: TypeResolver;
+    exampleResolver: ExampleResolver;
     file: FernFileContext;
 }) {
     const responseBodyType = typeof endpoint.response !== "string" ? endpoint.response?.type : endpoint.response;
@@ -318,6 +341,7 @@ function convertExampleResponseBody({
         example: example.response?.body,
         rawTypeBeingExemplified: responseBodyType,
         typeResolver,
+        exampleResolver,
         file,
     });
 }

packages/cli/generation/ir-generator/src/converters/services/convertHttpService.ts

@@ -3,6 +3,7 @@ import { RawSchemas } from "@fern-api/yaml-schema";
 import { HttpEndpoint, HttpHeader, HttpMethod, HttpService, PathParameter } from "@fern-fern/ir-model/services/http";
 import { FernFileContext } from "../../FernFileContext";
 import { ErrorResolver } from "../../resolvers/ErrorResolver";
+import { ExampleResolver } from "../../resolvers/ExampleResolver";
 import { TypeResolver } from "../../resolvers/TypeResolver";
 import { convertDeclaration } from "../convertDeclaration";
 import { constructHttpPath } from "./constructHttpPath";
@@ -19,12 +20,14 @@ export function convertHttpService({
     file,
     errorResolver,
     typeResolver,
+    exampleResolver,
 }: {
     serviceDefinition: RawSchemas.HttpServiceSchema;
     serviceId: string;
     file: FernFileContext;
     errorResolver: ErrorResolver;
     typeResolver: TypeResolver;
+    exampleResolver: ExampleResolver;
 }): HttpService {
     return {
         ...convertDeclaration(serviceDefinition),
@@ -116,6 +119,7 @@ export function convertHttpService({
                                   example,
                                   typeResolver,
                                   errorResolver,
+                                  exampleResolver,
                                   file,
                               })
                           )