feat(cli): streaming endpoint takes in description (#4766)

fern-api · Sep 26, 2024 · 0156c97 · 0156c97
1 parent fe56df4
commit 0156c97
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 0 deletions.
diff --git a/packages/cli/cli/versions.yml b/packages/cli/cli/versions.yml
@@ -1,3 +1,21 @@
+- changelogEntry:
+    - summary: |
+        If you use the `x-fern-streaming` extension and want to provide different descriptions 
+        for the streaming endpoint, then you can now specify `streaming-description`. 
+
+        ```yml openapi.yml
+        x-fern-streaming: 
+          stream-condition: $request.stream
+          stream-description: The streaming version of this endpoint returns a series of chunks ... 
+          response: 
+            $ref: #/components/schemas/Response
+          stream-response: 
+            $ref: #/components/schemas/ResponseChunk
+        ```
+      type: fix
+  irVersion: 53
+  version: 0.43.5
+
 - changelogEntry:
     - summary: |
         The OpenAPI parser now respects the content type in your OpenAPI spec, instead of always sending

diff --git a/packages/cli/openapi-parser/src/openapi/v3/converters/operation/convertStreamingOperation.ts b/packages/cli/openapi-parser/src/openapi/v3/converters/operation/convertStreamingOperation.ts
@@ -68,6 +68,7 @@ export function convertStreamingOperation({
                             : undefined,
                     operation: {
                         ...operationContext.operation,
+                        description: streamingExtension.streamDescription ?? operationContext.operation.description,
                         requestBody: streamingRequestBody?.requestBody,
                         responses: streamingResponses
                     },

diff --git a/packages/cli/openapi-parser/src/openapi/v3/extensions/fernExtensions.ts b/packages/cli/openapi-parser/src/openapi/v3/extensions/fernExtensions.ts
@@ -93,6 +93,7 @@ export const FernOpenAPIExtension = {
      *       x-fern-streaming:
      *         format: sse # or json
      *         stream-condition: $request.stream
+     *         stream-description: A description
      *         response:
      *           $ref: ./path/to/response/type.yaml
      *         response-stream:

diff --git a/packages/cli/openapi-parser/src/openapi/v3/extensions/getFernStreamingExtension.ts b/packages/cli/openapi-parser/src/openapi/v3/extensions/getFernStreamingExtension.ts
@@ -14,6 +14,7 @@ export interface OnlyStreamingEndpoint {
 export interface StreamConditionEndpoint {
     type: "streamCondition";
     format: "sse" | "json";
+    streamDescription: string | undefined;
     streamConditionProperty: string;
     responseStream: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
     response: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
@@ -25,6 +26,7 @@ declare namespace Raw {
     export interface StreamingExtensionObjectSchema {
         ["stream-condition"]: string;
         ["format"]: "sse" | "json" | undefined;
+        ["stream-description"]: string | undefined;
         ["response-stream"]: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
         response: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
     }
@@ -56,6 +58,7 @@ export function getFernStreamingExtension(operation: OpenAPIV3.OperationObject):
     return {
         type: "streamCondition",
         format: streaming.format ?? "json", // Default to "json"
+        streamDescription: streaming["stream-description"],
         streamConditionProperty: maybeTrimRequestPrefix(streaming["stream-condition"]),
         responseStream: streaming["response-stream"],
         response: streaming.response