feat: OpenApi Parser multiple success responses, error response descriptions, better examples

fern/apis/fdr/definition/api/latest/endpoint.yml

@@ -31,8 +31,8 @@ types:
       queryParameters: optional<list<type.ObjectProperty>>
       requestHeaders: optional<list<type.ObjectProperty>>
       responseHeaders: optional<list<type.ObjectProperty>> # this is not being used currently
-      request: optional<HttpRequest>
-      response: optional<HttpResponse>
+      requests: optional<list<HttpRequest>>
+      responses: optional<list<HttpResponse>>
       errors: optional<list<ErrorResponse>>
       examples: optional<list<ExampleEndpointCall>>
       snippetTemplates: optional<EndpointSnippetTemplates>

packages/fdr-sdk/src/api-definition/__test__/join.test.ts

@@ -43,8 +43,8 @@ const endpoint1: Latest.EndpointDefinition = {
   ],
   requestHeaders: undefined,
   responseHeaders: undefined,
-  request: undefined,
-  response: undefined,
+  requests: undefined,
+  responses: undefined,
   auth: undefined,
   description: undefined,
   availability: undefined,
@@ -83,8 +83,8 @@ const endpoint2: Latest.EndpointDefinition = {
     },
   ],
   responseHeaders: undefined,
-  request: undefined,
-  response: undefined,
+  requests: undefined,
+  responses: undefined,
   auth: [Latest.AuthSchemeId("auth")],
   description: undefined,
   availability: undefined,

packages/fdr-sdk/src/api-definition/__test__/prune.test.ts

@@ -43,8 +43,8 @@ const endpoint1: Latest.EndpointDefinition = {
   ],
   requestHeaders: undefined,
   responseHeaders: undefined,
-  request: undefined,
-  response: undefined,
+  requests: undefined,
+  responses: undefined,
   auth: undefined,
   description: undefined,
   availability: undefined,
@@ -83,8 +83,8 @@ const endpoint2: Latest.EndpointDefinition = {
     },
   ],
   responseHeaders: undefined,
-  request: undefined,
-  response: undefined,
+  requests: undefined,
+  responses: undefined,
   auth: [Latest.AuthSchemeId("auth")],
   description: undefined,
   availability: undefined,

packages/fdr-sdk/src/api-definition/migrators/v1ToV2.ts

@@ -1,3 +1,4 @@
+import { isNonNullish } from "@fern-api/ui-core-utils";
 import titleCase from "@fern-api/ui-core-utils/titleCase";
 import visitDiscriminatedUnion from "@fern-api/ui-core-utils/visitDiscriminatedUnion";
 import { mapValues } from "es-toolkit/object";
@@ -22,7 +23,7 @@ interface Flags {
 
   /**
    * If true, avoid generating Typescript SDK snippets.
-   * In @fern-docs/ui's resolver, we generate http-snippets for JavaScript.
+   * In @fern-ui/ui's resolver, we generate http-snippets for JavaScript.
    */
   alwaysEnableJavaScriptFetch: boolean;
 
@@ -191,8 +192,8 @@ export class ApiDefinitionV1ToLatest {
       queryParameters: this.migrateParameters(v1.queryParameters),
       requestHeaders: this.migrateParameters(v1.headers),
       responseHeaders: undefined,
-      request: this.migrateHttpRequest(v1.request),
-      response: this.migrateHttpResponse(v1.response),
+      requests: [this.migrateHttpRequest(v1.request)].filter(isNonNullish),
+      responses: [this.migrateHttpResponse(v1.response)].filter(isNonNullish),
       errors: this.migrateHttpErrors(v1.errorsV2),
       examples: undefined,
       snippetTemplates: v1.snippetTemplates,
@@ -455,6 +456,7 @@ export class ApiDefinitionV1ToLatest {
     if (examples.length === 0) {
       return undefined;
     }
+
     return examples.map((example): V2.ExampleEndpointCall => {
       const toRet: V2.ExampleEndpointCall = {
         path: example.path,
@@ -478,7 +480,7 @@ export class ApiDefinitionV1ToLatest {
             type: "json",
             value: sortKeysByShape(
               value.value,
-              endpoint.request?.body,
+              endpoint.requests?.[0]?.body,
               this.types
             ),
           }),
@@ -489,8 +491,8 @@ export class ApiDefinitionV1ToLatest {
               (formValue, key): APIV1Read.FormValue => {
                 if (formValue.type === "json") {
                   const shape =
-                    endpoint.request?.body.type === "formData"
-                      ? endpoint.request.body.fields.find(
+                    endpoint.requests?.[0]?.body.type === "formData"
+                      ? endpoint.requests?.[0]?.body.fields.find(
                           (field): field is V2.FormDataField.Property =>
                             field.key === key && field.type === "property"
                         )?.valueShape
@@ -511,7 +513,7 @@ export class ApiDefinitionV1ToLatest {
       if (toRet.responseBody) {
         toRet.responseBody.value = sortKeysByShape(
           toRet.responseBody.value,
-          endpoint.response?.body,
+          endpoint.responses?.[0]?.body,
           this.types
         );
       }

packages/fdr-sdk/src/api-definition/snippets/SnippetHttpRequest.ts

@@ -98,8 +98,8 @@ export function toSnippetHttpRequest(
 
   const body: Latest.ExampleEndpointRequest | undefined = example.requestBody;
 
-  if (endpoint.request?.contentType != null) {
-    headers["Content-Type"] = endpoint.request?.contentType;
+  if (endpoint.requests?.[0]?.contentType != null) {
+    headers["Content-Type"] = endpoint.requests?.[0]?.contentType;
   }
 
   if (body != null && headers["Content-Type"] == null) {

packages/fdr-sdk/src/api-definition/transformer.ts

@@ -320,12 +320,17 @@ export class Transformer {
           `${parentKey}/responseHeader/${param.key}`
         )
       ) ?? [];
-    const request = endpoint.request
-      ? this.visitor.HttpRequest(endpoint.request, `${parentKey}/request`)
-      : undefined;
-    const response = endpoint.response
-      ? this.visitor.HttpResponse(endpoint.response, `${parentKey}/response`)
-      : undefined;
+    const requests = endpoint.requests?.map((request, i) =>
+      // this has changed
+      this.visitor.HttpRequest(request, `${parentKey}/request/${i}`)
+    );
+    const responses = endpoint.responses?.map((response, i) =>
+      // this has changed discretely
+      this.visitor.HttpResponse(
+        response,
+        `${parentKey}/response/${i}/${response.statusCode}`
+      )
+    );
     const errors =
       endpoint.errors?.map((error, i) =>
         this.visitor.ErrorResponse(
@@ -344,8 +349,8 @@ export class Transformer {
       queryParameters: queryParameters.length > 0 ? queryParameters : undefined,
       requestHeaders: requestHeaders.length > 0 ? requestHeaders : undefined,
       responseHeaders: responseHeaders.length > 0 ? responseHeaders : undefined,
-      request,
-      response,
+      requests,
+      responses,
       errors: errors.length > 0 ? errors : undefined,
       examples: examples.length > 0 ? examples : undefined,
     };

packages/fdr-sdk/src/api-definition/typeid-visitor.ts

@@ -19,16 +19,16 @@ export class ApiTypeIdVisitor {
     endpoint.responseHeaders?.forEach((header) => {
       ApiTypeIdVisitor.visitTypeShape(header.valueShape, visit);
     });
-    if (endpoint.request?.body != null) {
-      ApiTypeIdVisitor.visitHttpRequestBodyShape(endpoint.request.body, visit);
-    }
-    if (endpoint.response?.body != null) {
-      ApiTypeIdVisitor.visitHttpResponseBodyShape(
-        endpoint.response.body,
-        visit
-      );
-    }
-
+    endpoint.requests?.forEach((request) => {
+      if (request.body != null) {
+        ApiTypeIdVisitor.visitHttpRequestBodyShape(request.body, visit);
+      }
+    });
+    endpoint.responses?.forEach((response) => {
+      if (response.body != null) {
+        ApiTypeIdVisitor.visitHttpResponseBodyShape(response.body, visit);
+      }
+    });
     endpoint.errors?.forEach((error) => {
       if (error.shape != null) {
         ApiTypeIdVisitor.visitTypeShape(error.shape, visit);