feat: show error schemas in docs (#3401)

* update openapi-parser * update openapi-ir-to-fern * fix openapi-parser tests * add snaps * add example description * fix error typename * fix tests * restore missing examples * init uploadcare error * fix: add error examples * generate docs
fern-api · Apr 23, 2024 · 367cc76 · 367cc76
1 parent 15e024f
commit 367cc76
Show file tree

Hide file tree

Showing 112 changed files with 228,543 additions and 9,717 deletions.
diff --git a/packages/cli/cli/src/commands/generate/generateDocsWorkspace.ts b/packages/cli/cli/src/commands/generate/generateDocsWorkspace.ts
@@ -48,7 +48,7 @@ export async function generateDocsWorkspace({
             project.apiWorkspaces.map(async (workspace) => {
                 return workspace.type === "fern"
                     ? workspace
-                    : await convertOpenApiWorkspaceToFernWorkspace(workspace, context);
+                    : await convertOpenApiWorkspaceToFernWorkspace(workspace, context, true);
             })
         );
 

diff --git a/packages/cli/openapi-ir-sdk/fern/definition/finalIr.yml b/packages/cli/openapi-ir-sdk/fern/definition/finalIr.yml
@@ -8,26 +8,25 @@ types:
       title: optional<string>
       description: optional<string>
       servers: list<commons.Server>
-      groups: 
+      groups:
         docs: |
-          Top level group information populated through `x-fern-groups`. 
+          Top level group information populated through `x-fern-groups`.
         type: map<string, SdkGroupInfo>
       tags: Tags
       hasEndpointsMarkedInternal: boolean
       endpoints: list<Endpoint>
       webhooks: list<Webhook>
       channel: list<WebsocketChannel>
       schemas: map<commons.SchemaId, Schema>
-      errors: map<commons.StatusCode, HttpError>
       variables: map<string, PrimitiveSchema>
       nonRequestReferencedSchemas:
         type: set<commons.SchemaId>
         docs: Whether the schema is directly referenced from a response, parameters, or other schemas
       securitySchemes: map<commons.SecuritySchemeId, commons.SecurityScheme>
       globalHeaders: optional<list<GlobalHeader>>
 
-  SdkGroupInfo: 
-    properties: 
+  SdkGroupInfo:
+    properties:
       summary: optional<string>
       description: optional<string>
 
@@ -50,6 +49,7 @@ types:
       - commons.WithName
     properties:
       schema: optional<Schema>
+      examples: optional<list<ErrorExample>>
 
   Webhook:
     extends: commons.WithDescription
@@ -139,7 +139,11 @@ types:
           Populated by `x-request-name` on a path object.
       request: optional<Request>
       response: optional<Response>
-      errorStatusCode: list<commons.StatusCode>
+      errors:
+        type: map<commons.StatusCode, HttpError>
+        docs: |
+          Expected error status codes for this endpoint, and their corresponding schema and examples.
+          SDK generators will only read the StatusCodes. Docs generators will read the HttpError schema.
       server: list<commons.Server>
       examples: list<EndpointExample>
 
@@ -232,6 +236,12 @@ types:
       name: string
       value: example.FullExample
 
+  ErrorExample:
+    properties:
+      name: optional<string>
+      description: optional<string>
+      example: example.FullExample
+
   EndpointSdkName:
     properties:
       groupName:

diff --git a/packages/cli/openapi-ir-sdk/fern/definition/parseIr.yml b/packages/cli/openapi-ir-sdk/fern/definition/parseIr.yml
@@ -4,6 +4,7 @@ imports:
 
 types:
   NamedFullExample:
+    extends: commons.WithDescription
     properties:
       name: optional<string>
       value: unknown
@@ -43,14 +44,27 @@ types:
           Populated by `x-request-name` on a path object.
       request: optional<RequestWithExample>
       response: optional<ResponseWithExample>
-      errorStatusCode: list<commons.StatusCode>
+      errors:
+        type: map<commons.StatusCode, HttpErrorWithExample>
+        docs: |
+          Expected error status codes for this endpoint, and their corresponding schema and examples.
+          SDK generators will only read the StatusCodes. Docs generators will read the HttpError schema.
       server: list<commons.Server>
       examples:
         type: list<finalIr.EndpointExample>
         docs: |
           Populated by `x-fern-examples` on a path object.
           Also migrated from `x-readme.code-samples` if present.
 
+  HttpErrorWithExample:
+    extends:
+      - commons.WithDescription
+      - commons.WithName
+    properties:
+      statusCode: commons.StatusCode
+      schema: SchemaWithExample
+      fullExamples: optional<list<NamedFullExample>>
+
   RequestWithExample:
     union:
       octetStream: finalIr.OctetStreamRequest

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/Endpoint.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/Endpoint.ts
@@ -28,7 +28,11 @@ export interface Endpoint extends FernOpenapiIr.WithDescription {
     requestNameOverride: string | undefined;
     request: FernOpenapiIr.Request | undefined;
     response: FernOpenapiIr.Response | undefined;
-    errorStatusCode: FernOpenapiIr.StatusCode[];
+    /**
+     * Expected error status codes for this endpoint, and their corresponding schema and examples.
+     * SDK generators will only read the StatusCodes. Docs generators will read the HttpError schema.
+     */
+    errors: Record<FernOpenapiIr.StatusCode, FernOpenapiIr.HttpError>;
     server: FernOpenapiIr.Server[];
     examples: FernOpenapiIr.EndpointExample[];
 }
diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/ErrorExample.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/ErrorExample.ts
@@ -0,0 +1,11 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernOpenapiIr from "../../..";
+
+export interface ErrorExample {
+    name: string | undefined;
+    description: string | undefined;
+    example: FernOpenapiIr.FullExample;
+}
diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/HttpError.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/HttpError.ts
@@ -6,4 +6,5 @@ import * as FernOpenapiIr from "../../..";
 
 export interface HttpError extends FernOpenapiIr.WithDescription, FernOpenapiIr.WithName {
     schema: FernOpenapiIr.Schema | undefined;
+    examples: FernOpenapiIr.ErrorExample[] | undefined;
 }
diff --git a/...i/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/OpenApiIntermediateRepresentation.ts b/...i/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/OpenApiIntermediateRepresentation.ts
@@ -16,7 +16,6 @@ export interface OpenApiIntermediateRepresentation {
     webhooks: FernOpenapiIr.Webhook[];
     channel: FernOpenapiIr.WebsocketChannel[];
     schemas: Record<FernOpenapiIr.SchemaId, FernOpenapiIr.Schema>;
-    errors: Record<FernOpenapiIr.StatusCode, FernOpenapiIr.HttpError>;
     variables: Record<string, FernOpenapiIr.PrimitiveSchema>;
     /** Whether the schema is directly referenced from a response, parameters, or other schemas */
     nonRequestReferencedSchemas: Set<FernOpenapiIr.SchemaId>;

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/index.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/index.ts
@@ -21,6 +21,7 @@ export * from "./FullEndpointExample";
 export * from "./PathParameterExample";
 export * from "./QueryParameterExample";
 export * from "./HeaderExample";
+export * from "./ErrorExample";
 export * from "./EndpointSdkName";
 export * from "./HttpMethod";
 export * from "./PathParameter";

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/EndpointWithExample.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/EndpointWithExample.ts
@@ -28,7 +28,11 @@ export interface EndpointWithExample extends FernOpenapiIr.WithDescription {
     requestNameOverride: string | undefined;
     request: FernOpenapiIr.RequestWithExample | undefined;
     response: FernOpenapiIr.ResponseWithExample | undefined;
-    errorStatusCode: FernOpenapiIr.StatusCode[];
+    /**
+     * Expected error status codes for this endpoint, and their corresponding schema and examples.
+     * SDK generators will only read the StatusCodes. Docs generators will read the HttpError schema.
+     */
+    errors: Record<FernOpenapiIr.StatusCode, FernOpenapiIr.HttpErrorWithExample>;
     server: FernOpenapiIr.Server[];
     /**
      * Populated by `x-fern-examples` on a path object.

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/HttpErrorWithExample.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/HttpErrorWithExample.ts
@@ -0,0 +1,11 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernOpenapiIr from "../../..";
+
+export interface HttpErrorWithExample extends FernOpenapiIr.WithDescription, FernOpenapiIr.WithName {
+    statusCode: FernOpenapiIr.StatusCode;
+    schema: FernOpenapiIr.SchemaWithExample;
+    fullExamples: FernOpenapiIr.NamedFullExample[] | undefined;
+}
diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/NamedFullExample.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/NamedFullExample.ts
@@ -2,7 +2,9 @@
  * This file was auto-generated by Fern from our API Definition.
  */
 
-export interface NamedFullExample {
+import * as FernOpenapiIr from "../../..";
+
+export interface NamedFullExample extends FernOpenapiIr.WithDescription {
     name: string | undefined;
     value: unknown;
 }
diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/index.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/parseIr/types/index.ts
@@ -1,6 +1,7 @@
 export * from "./NamedFullExample";
 export * from "./WebsocketHandshakeWithExample";
 export * from "./EndpointWithExample";
+export * from "./HttpErrorWithExample";
 export * from "./RequestWithExample";
 export * from "./JsonRequestWithExample";
 export * from "./ResponseWithExample";

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/Endpoint.ts b/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/Endpoint.ts
@@ -34,8 +34,9 @@ export const Endpoint: core.serialization.ObjectSchema<serializers.Endpoint.Raw,
             requestNameOverride: core.serialization.string().optional(),
             request: core.serialization.lazy(async () => (await import("../../..")).Request).optional(),
             response: core.serialization.lazy(async () => (await import("../../..")).Response).optional(),
-            errorStatusCode: core.serialization.list(
-                core.serialization.lazy(async () => (await import("../../..")).StatusCode)
+            errors: core.serialization.record(
+                core.serialization.lazy(async () => (await import("../../..")).StatusCode),
+                core.serialization.lazyObject(async () => (await import("../../..")).HttpError)
             ),
             server: core.serialization.list(
                 core.serialization.lazyObject(async () => (await import("../../..")).Server)
@@ -65,7 +66,7 @@ export declare namespace Endpoint {
         requestNameOverride?: string | null;
         request?: serializers.Request.Raw | null;
         response?: serializers.Response.Raw | null;
-        errorStatusCode: serializers.StatusCode.Raw[];
+        errors: Record<serializers.StatusCode.Raw, serializers.HttpError.Raw>;
         server: serializers.Server.Raw[];
         examples: serializers.EndpointExample.Raw[];
     }

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/ErrorExample.ts b/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/ErrorExample.ts
@@ -0,0 +1,22 @@
+/**
+ * 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 ErrorExample: core.serialization.ObjectSchema<serializers.ErrorExample.Raw, FernOpenapiIr.ErrorExample> =
+    core.serialization.objectWithoutOptionalProperties({
+        name: core.serialization.string().optional(),
+        description: core.serialization.string().optional(),
+        example: core.serialization.lazy(async () => (await import("../../..")).FullExample),
+    });
+
+export declare namespace ErrorExample {
+    interface Raw {
+        name?: string | null;
+        description?: string | null;
+        example: serializers.FullExample.Raw;
+    }
+}
diff --git a/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/HttpError.ts b/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/HttpError.ts
@@ -10,12 +10,16 @@ export const HttpError: core.serialization.ObjectSchema<serializers.HttpError.Ra
     core.serialization
         .objectWithoutOptionalProperties({
             schema: core.serialization.lazy(async () => (await import("../../..")).Schema).optional(),
+            examples: core.serialization
+                .list(core.serialization.lazyObject(async () => (await import("../../..")).ErrorExample))
+                .optional(),
         })
         .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithDescription))
         .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithName));
 
 export declare namespace HttpError {
     interface Raw extends serializers.WithDescription.Raw, serializers.WithName.Raw {
         schema?: serializers.Schema.Raw | null;
+        examples?: serializers.ErrorExample.Raw[] | null;
     }
 }
diff --git a/...ir-sdk/src/sdk/serialization/resources/finalIr/types/OpenApiIntermediateRepresentation.ts b/...ir-sdk/src/sdk/serialization/resources/finalIr/types/OpenApiIntermediateRepresentation.ts
@@ -28,10 +28,6 @@ export const OpenApiIntermediateRepresentation: core.serialization.ObjectSchema<
         core.serialization.lazy(async () => (await import("../../..")).SchemaId),
         core.serialization.lazy(async () => (await import("../../..")).Schema)
     ),
-    errors: core.serialization.record(
-        core.serialization.lazy(async () => (await import("../../..")).StatusCode),
-        core.serialization.lazyObject(async () => (await import("../../..")).HttpError)
-    ),
     variables: core.serialization.record(
         core.serialization.string(),
         core.serialization.lazyObject(async () => (await import("../../..")).PrimitiveSchema)
@@ -60,7 +56,6 @@ export declare namespace OpenApiIntermediateRepresentation {
         webhooks: serializers.Webhook.Raw[];
         channel: serializers.WebsocketChannel.Raw[];
         schemas: Record<serializers.SchemaId.Raw, serializers.Schema.Raw>;
-        errors: Record<serializers.StatusCode.Raw, serializers.HttpError.Raw>;
         variables: Record<string, serializers.PrimitiveSchema.Raw>;
         nonRequestReferencedSchemas: serializers.SchemaId.Raw[];
         securitySchemes: Record<serializers.SecuritySchemeId.Raw, serializers.SecurityScheme.Raw>;

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/index.ts b/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/index.ts
@@ -21,6 +21,7 @@ export * from "./FullEndpointExample";
 export * from "./PathParameterExample";
 export * from "./QueryParameterExample";
 export * from "./HeaderExample";
+export * from "./ErrorExample";
 export * from "./EndpointSdkName";
 export * from "./HttpMethod";
 export * from "./PathParameter";

diff --git a/...s/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/EndpointWithExample.ts b/...s/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/EndpointWithExample.ts
@@ -34,8 +34,9 @@ export const EndpointWithExample: core.serialization.ObjectSchema<
         requestNameOverride: core.serialization.string().optional(),
         request: core.serialization.lazy(async () => (await import("../../..")).RequestWithExample).optional(),
         response: core.serialization.lazy(async () => (await import("../../..")).ResponseWithExample).optional(),
-        errorStatusCode: core.serialization.list(
-            core.serialization.lazy(async () => (await import("../../..")).StatusCode)
+        errors: core.serialization.record(
+            core.serialization.lazy(async () => (await import("../../..")).StatusCode),
+            core.serialization.lazyObject(async () => (await import("../../..")).HttpErrorWithExample)
         ),
         server: core.serialization.list(core.serialization.lazyObject(async () => (await import("../../..")).Server)),
         examples: core.serialization.list(
@@ -63,7 +64,7 @@ export declare namespace EndpointWithExample {
         requestNameOverride?: string | null;
         request?: serializers.RequestWithExample.Raw | null;
         response?: serializers.ResponseWithExample.Raw | null;
-        errorStatusCode: serializers.StatusCode.Raw[];
+        errors: Record<serializers.StatusCode.Raw, serializers.HttpErrorWithExample.Raw>;
         server: serializers.Server.Raw[];
         examples: serializers.EndpointExample.Raw[];
     }

diff --git a/.../cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/HttpErrorWithExample.ts b/.../cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/HttpErrorWithExample.ts
@@ -0,0 +1,29 @@
+/**
+ * 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 HttpErrorWithExample: core.serialization.ObjectSchema<
+    serializers.HttpErrorWithExample.Raw,
+    FernOpenapiIr.HttpErrorWithExample
+> = core.serialization
+    .objectWithoutOptionalProperties({
+        statusCode: core.serialization.lazy(async () => (await import("../../..")).StatusCode),
+        schema: core.serialization.lazy(async () => (await import("../../..")).SchemaWithExample),
+        fullExamples: core.serialization
+            .list(core.serialization.lazyObject(async () => (await import("../../..")).NamedFullExample))
+            .optional(),
+    })
+    .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithDescription))
+    .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithName));
+
+export declare namespace HttpErrorWithExample {
+    interface Raw extends serializers.WithDescription.Raw, serializers.WithName.Raw {
+        statusCode: serializers.StatusCode.Raw;
+        schema: serializers.SchemaWithExample.Raw;
+        fullExamples?: serializers.NamedFullExample.Raw[] | null;
+    }
+}
diff --git a/...ages/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/NamedFullExample.ts b/...ages/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/NamedFullExample.ts
@@ -9,13 +9,15 @@ import * as core from "../../../../core";
 export const NamedFullExample: core.serialization.ObjectSchema<
     serializers.NamedFullExample.Raw,
     FernOpenapiIr.NamedFullExample
-> = core.serialization.objectWithoutOptionalProperties({
-    name: core.serialization.string().optional(),
-    value: core.serialization.unknown(),
-});
+> = core.serialization
+    .objectWithoutOptionalProperties({
+        name: core.serialization.string().optional(),
+        value: core.serialization.unknown(),
+    })
+    .extend(core.serialization.lazyObject(async () => (await import("../../..")).WithDescription));
 
 export declare namespace NamedFullExample {
-    interface Raw {
+    interface Raw extends serializers.WithDescription.Raw {
         name?: string | null;
         value?: unknown;
     }

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/index.ts b/packages/cli/openapi-ir-sdk/src/sdk/serialization/resources/parseIr/types/index.ts
@@ -1,6 +1,7 @@
 export * from "./NamedFullExample";
 export * from "./WebsocketHandshakeWithExample";
 export * from "./EndpointWithExample";
+export * from "./HttpErrorWithExample";
 export * from "./RequestWithExample";
 export * from "./JsonRequestWithExample";
 export * from "./ResponseWithExample";