(feature): generate default examples for WebSocket Sessions (#3039)

default example generation for wss

packages/cli/openapi-ir-sdk/fern/definition/finalIr.yml

@@ -64,11 +64,28 @@ types:
       handshake: WebsocketHandshake
       publish: optional<Schema>
       subscribe: optional<Schema>
+      examples: list<WebsocketSessionExample>
 
   WebsocketHandshake: 
     properties: 
       queryParameters: list<QueryParameter>
       headers: list<Header>
+
+  WebsocketSessionExample:
+    docs: |
+      A complete example associated with the websocket channel.
+    extends: commons.WithDescription
+    properties:
+      name: optional<string>
+      queryParameters: optional<list<QueryParameterExample>>
+      headers: optional<list<HeaderExample>>
+      messages: list<WebsocketMessageExample>
+
+  WebsocketMessageExample: 
+    extends: commons.WithDescription
+    properties: 
+      messageType: string
+      payload: example.FullExample
 
   WebhookHttpMethod:
     enum:

packages/cli/openapi-ir-sdk/fern/definition/parseIr.yml

@@ -7,6 +7,11 @@ types:
     properties:
       name: optional<string>
       value: unknown
+
+  WebsocketHandshakeWithExample: 
+    properties: 
+      queryParameters: list<QueryParameterWithExample>
+      headers: list<HeaderWithExample>
 
   EndpointWithExample:
     extends: commons.WithDescription

packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/WebsocketChannel.ts

@@ -11,4 +11,5 @@ export interface WebsocketChannel extends FernOpenapiIr.WithDescription {
     handshake: FernOpenapiIr.WebsocketHandshake;
     publish: FernOpenapiIr.Schema | undefined;
     subscribe: FernOpenapiIr.Schema | undefined;
+    examples: FernOpenapiIr.WebsocketSessionExample[];
 }

packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/WebsocketMessageExample.ts

@@ -0,0 +1,10 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernOpenapiIr from "../../..";
+
+export interface WebsocketMessageExample extends FernOpenapiIr.WithDescription {
+    messageType: string;
+    payload: FernOpenapiIr.FullExample;
+}

packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/WebsocketSessionExample.ts

@@ -0,0 +1,15 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernOpenapiIr from "../../..";
+
+/**
+ * A complete example associated with the websocket channel.
+ */
+export interface WebsocketSessionExample extends FernOpenapiIr.WithDescription {
+    name: string | undefined;
+    queryParameters: FernOpenapiIr.QueryParameterExample[] | undefined;
+    headers: FernOpenapiIr.HeaderExample[] | undefined;
+    messages: FernOpenapiIr.WebsocketMessageExample[];
+}

packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/index.ts

@@ -5,6 +5,8 @@ export * from "./HttpError";
 export * from "./Webhook";
 export * from "./WebsocketChannel";
 export * from "./WebsocketHandshake";
+export * from "./WebsocketSessionExample";
+export * from "./WebsocketMessageExample";
 export * from "./WebhookHttpMethod";
 export * from "./EndpointAvailability";
 export * from "./Endpoint";

packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/WebsocketHandshakeWithExample.ts

@@ -0,0 +1,10 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernOpenapiIr from "../../..";
+
+export interface WebsocketHandshakeWithExample {
+    queryParameters: FernOpenapiIr.QueryParameterWithExample[];
+    headers: FernOpenapiIr.HeaderWithExample[];
+}

packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/index.ts

@@ -1,4 +1,5 @@
 export * from "./NamedFullExample";
+export * from "./WebsocketHandshakeWithExample";
 export * from "./EndpointWithExample";
 export * from "./RequestWithExample";
 export * from "./JsonRequestWithExample";

packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/WebsocketChannel.ts

@@ -19,6 +19,9 @@ export const WebsocketChannel: core.serialization.ObjectSchema<
         handshake: core.serialization.lazyObject(async () => (await import("../../..")).WebsocketHandshake),
         publish: core.serialization.lazy(async () => (await import("../../..")).Schema).optional(),
         subscribe: core.serialization.lazy(async () => (await import("../../..")).Schema).optional(),
+        examples: core.serialization.list(
+            core.serialization.lazyObject(async () => (await import("../../..")).WebsocketSessionExample)
+        ),
     })
     .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithDescription));
 
@@ -30,5 +33,6 @@ export declare namespace WebsocketChannel {
         handshake: serializers.WebsocketHandshake.Raw;
         publish?: serializers.Schema.Raw | null;
         subscribe?: serializers.Schema.Raw | null;
+        examples: serializers.WebsocketSessionExample.Raw[];
     }
 }

packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/WebsocketMessageExample.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernOpenapiIr from "../../../../api";
+import * as core from "../../../../core";
+
+export const WebsocketMessageExample: core.serialization.ObjectSchema<
+    serializers.WebsocketMessageExample.Raw,
+    FernOpenapiIr.WebsocketMessageExample
+> = core.serialization
+    .objectWithoutOptionalProperties({
+        messageType: core.serialization.string(),
+        payload: core.serialization.lazy(async () => (await import("../../..")).FullExample),
+    })
+    .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithDescription));
+
+export declare namespace WebsocketMessageExample {
+    interface Raw extends serializers.WithDescription.Raw {
+        messageType: string;
+        payload: serializers.FullExample.Raw;
+    }
+}

packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/WebsocketSessionExample.ts

@@ -0,0 +1,34 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernOpenapiIr from "../../../../api";
+import * as core from "../../../../core";
+
+export const WebsocketSessionExample: core.serialization.ObjectSchema<
+    serializers.WebsocketSessionExample.Raw,
+    FernOpenapiIr.WebsocketSessionExample
+> = core.serialization
+    .objectWithoutOptionalProperties({
+        name: core.serialization.string().optional(),
+        queryParameters: core.serialization
+            .list(core.serialization.lazyObject(async () => (await import("../../..")).QueryParameterExample))
+            .optional(),
+        headers: core.serialization
+            .list(core.serialization.lazyObject(async () => (await import("../../..")).HeaderExample))
+            .optional(),
+        messages: core.serialization.list(
+            core.serialization.lazyObject(async () => (await import("../../..")).WebsocketMessageExample)
+        ),
+    })
+    .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithDescription));
+
+export declare namespace WebsocketSessionExample {
+    interface Raw extends serializers.WithDescription.Raw {
+        name?: string | null;
+        queryParameters?: serializers.QueryParameterExample.Raw[] | null;
+        headers?: serializers.HeaderExample.Raw[] | null;
+        messages: serializers.WebsocketMessageExample.Raw[];
+    }
+}

packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/index.ts

@@ -5,6 +5,8 @@ export * from "./HttpError";
 export * from "./Webhook";
 export * from "./WebsocketChannel";
 export * from "./WebsocketHandshake";
+export * from "./WebsocketSessionExample";
+export * from "./WebsocketMessageExample";
 export * from "./WebhookHttpMethod";
 export * from "./EndpointAvailability";
 export * from "./Endpoint";

packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/WebsocketHandshakeWithExample.ts

@@ -0,0 +1,26 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernOpenapiIr from "../../../../api";
+import * as core from "../../../../core";
+
+export const WebsocketHandshakeWithExample: core.serialization.ObjectSchema<
+    serializers.WebsocketHandshakeWithExample.Raw,
+    FernOpenapiIr.WebsocketHandshakeWithExample
+> = core.serialization.objectWithoutOptionalProperties({
+    queryParameters: core.serialization.list(
+        core.serialization.lazyObject(async () => (await import("../../..")).QueryParameterWithExample)
+    ),
+    headers: core.serialization.list(
+        core.serialization.lazyObject(async () => (await import("../../..")).HeaderWithExample)
+    ),
+});
+
+export declare namespace WebsocketHandshakeWithExample {
+    interface Raw {
+        queryParameters: serializers.QueryParameterWithExample.Raw[];
+        headers: serializers.HeaderWithExample.Raw[];
+    }
+}

packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/index.ts

@@ -1,4 +1,5 @@
 export * from "./NamedFullExample";
+export * from "./WebsocketHandshakeWithExample";
 export * from "./EndpointWithExample";
 export * from "./RequestWithExample";
 export * from "./JsonRequestWithExample";

packages/cli/openapi-ir-to-fern/src/FernDefnitionBuilder.ts

@@ -52,6 +52,8 @@ export interface FernDefinitionBuilder {
         { messageId, message }: { messageId: string; message: RawSchemas.WebSocketChannelMessageSchema }
     ): void;
 
+    addChannelExample(file: RelativeFilePath, { example }: { example: RawSchemas.ExampleWebSocketSession }): void;
+
     setServiceInfo(file: RelativeFilePath, { displayName, docs }: { displayName?: string; docs?: string }): void;
 
     build(): FernDefinition;
@@ -233,6 +235,26 @@ export class FernDefinitionBuilderImpl implements FernDefinitionBuilder {
         fernFile.channel = channel;
     }
 
+    public addChannelExample(
+        file: RelativeFilePath,
+        { example }: { example: RawSchemas.ExampleWebSocketSession }
+    ): void {
+        const fernFile = this.getOrCreateFile(file);
+        if (fernFile.channel == null) {
+            fernFile.channel = {
+                path: "",
+                auth: false
+            };
+        }
+        if (fernFile.channel.messages == null) {
+            fernFile.channel.messages = {};
+        }
+        if (fernFile.channel.examples == null) {
+            fernFile.channel.examples = [];
+        }
+        fernFile.channel.examples.push(example);
+    }
+
     public addChannelMessage(
         file: RelativeFilePath,
         { messageId, message }: { messageId: string; message: RawSchemas.WebSocketChannelMessageSchema }

packages/cli/openapi-ir-to-fern/src/__test__/__snapshots__/assembly.test.ts.snap

@@ -291,6 +291,26 @@ The LLM response data, as well as any context provided in the original request w
     "realtime.yml": {
       "channel": {
         "auth": false,
+        "examples": [
+          {
+            "messages": [
+              {
+                "body": {
+                  "audio_data": "audio_data",
+                },
+                "type": "publish",
+              },
+              {
+                "body": {
+                  "expires_at": "2024-01-15T09:30:00Z",
+                  "message_type": "SessionBegins",
+                  "session_id": "session_id",
+                },
+                "type": "subscribe",
+              },
+            ],
+          },
+        ],
         "headers": {
           "Authentication": {
             "docs": "Authenticate using your AssemblyAI API key.",

packages/cli/openapi-ir-to-fern/src/buildChannel.ts

@@ -4,6 +4,7 @@ import { RawSchemas } from "@fern-api/yaml-schema";
 import { buildHeader } from "./buildHeader";
 import { buildQueryParameter } from "./buildQueryParameter";
 import { buildTypeReference } from "./buildTypeReference";
+import { buildWebsocketSessionExample } from "./buildWebsocketSessionExample";
 import { OpenApiIrConverterContext } from "./OpenApiIrConverterContext";
 
 export function buildChannel({
@@ -22,7 +23,7 @@ export function buildChannel({
     };
 
     const queryParameters: Record<string, RawSchemas.HttpQueryParameterSchema> = {};
-    if (channel.handshake != null && channel.handshake.queryParameters.length > 0) {
+    if (channel.handshake.queryParameters.length > 0) {
         for (const queryParameter of channel.handshake.queryParameters) {
             const convertedQueryParameter = buildQueryParameter({
                 queryParameter,
@@ -41,7 +42,7 @@ export function buildChannel({
     }
 
     const headers: Record<string, RawSchemas.HttpHeaderSchema> = {};
-    if (channel.handshake != null && channel.handshake.headers.length > 0) {
+    if (channel.handshake.headers.length > 0) {
         for (const header of channel.handshake.headers) {
             const headerSchema = buildHeader({ header, context, fileContainingReference: declarationFile });
             headers[header.name] = headerSchema;
@@ -82,4 +83,11 @@ export function buildChannel({
             }
         });
     }
+
+    for (const example of channel.examples) {
+        const websocketExample = buildWebsocketSessionExample({ context, websocketExample: example });
+        context.builder.addChannelExample(declarationFile, {
+            example: websocketExample
+        });
+    }
 }