(feat, openapi): add support for x-fern-idempotency-headers (#3746)

fern-api · May 31, 2024 · 3c2977a · 3c2977a
1 parent 0436951
commit 3c2977a
Show file tree

Hide file tree

Showing 65 changed files with 1,623 additions and 1 deletion.
diff --git a/packages/cli/openapi-ir-sdk/fern/definition/finalIr.yml b/packages/cli/openapi-ir-sdk/fern/definition/finalIr.yml
@@ -25,6 +25,7 @@ types:
         docs: Whether the schema is directly referenced from a response, parameters, or other schemas
       securitySchemes: map<commons.SecuritySchemeId, commons.SecurityScheme>
       globalHeaders: optional<list<GlobalHeader>>
+      idempotencyHeaders: optional<list<IdempotencyHeader>>
 
   SdkGroupInfo:
     properties:
@@ -38,6 +39,13 @@ types:
       optional: optional<boolean>
       env: optional<string>
       schema: optional<Schema>
+
+  IdempotencyHeader:
+    properties:
+      header: string
+      name: optional<string>
+      env: optional<string>
+      schema: optional<Schema>
 
   Tags:
     properties:
@@ -116,6 +124,7 @@ types:
     properties:
       authed: boolean
       internal: optional<boolean>
+      idempotent: optional<boolean>
       method: HttpMethod
       availability: optional<EndpointAvailability>
       audiences: list<string>

diff --git a/packages/cli/openapi-ir-sdk/fern/definition/parseIr.yml b/packages/cli/openapi-ir-sdk/fern/definition/parseIr.yml
@@ -19,6 +19,7 @@ types:
     properties:
       authed: boolean
       internal: optional<boolean>
+      idempotent: optional<boolean>
       method: finalIr.HttpMethod
       availability: optional<finalIr.EndpointAvailability>
       audiences: list<string>

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
@@ -7,6 +7,7 @@ import * as FernOpenapiIr from "../../..";
 export interface Endpoint extends FernOpenapiIr.WithDescription {
     authed: boolean;
     internal: boolean | undefined;
+    idempotent: boolean | undefined;
     method: FernOpenapiIr.HttpMethod;
     availability: FernOpenapiIr.EndpointAvailability | undefined;
     audiences: string[];

diff --git a/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/IdempotencyHeader.ts b/packages/cli/openapi-ir-sdk/src/sdk/api/resources/finalIr/types/IdempotencyHeader.ts
@@ -0,0 +1,12 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernOpenapiIr from "../../..";
+
+export interface IdempotencyHeader {
+    header: string;
+    name: string | undefined;
+    env: string | undefined;
+    schema: FernOpenapiIr.Schema | 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
@@ -22,4 +22,5 @@ export interface OpenApiIntermediateRepresentation {
     nonRequestReferencedSchemas: Set<FernOpenapiIr.SchemaId>;
     securitySchemes: Record<FernOpenapiIr.SecuritySchemeId, FernOpenapiIr.SecurityScheme>;
     globalHeaders: FernOpenapiIr.GlobalHeader[] | undefined;
+    idempotencyHeaders: FernOpenapiIr.IdempotencyHeader[] | undefined;
 }
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
@@ -1,6 +1,7 @@
 export * from "./OpenApiIntermediateRepresentation";
 export * from "./SdkGroupInfo";
 export * from "./GlobalHeader";
+export * from "./IdempotencyHeader";
 export * from "./Tags";
 export * from "./HttpError";
 export * from "./Webhook";

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
@@ -7,6 +7,7 @@ import * as FernOpenapiIr from "../../..";
 export interface EndpointWithExample extends FernOpenapiIr.WithDescription {
     authed: boolean;
     internal: boolean | undefined;
+    idempotent: boolean | undefined;
     method: FernOpenapiIr.HttpMethod;
     availability: FernOpenapiIr.EndpointAvailability | undefined;
     audiences: string[];

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
@@ -11,6 +11,7 @@ export const Endpoint: core.serialization.ObjectSchema<serializers.Endpoint.Raw,
         .objectWithoutOptionalProperties({
             authed: core.serialization.boolean(),
             internal: core.serialization.boolean().optional(),
+            idempotent: core.serialization.boolean().optional(),
             method: core.serialization.lazy(async () => (await import("../../..")).HttpMethod),
             availability: core.serialization
                 .lazy(async () => (await import("../../..")).EndpointAvailability)
@@ -52,6 +53,7 @@ export declare namespace Endpoint {
     interface Raw extends serializers.WithDescription.Raw {
         authed: boolean;
         internal?: boolean | null;
+        idempotent?: boolean | null;
         method: serializers.HttpMethod.Raw;
         availability?: serializers.EndpointAvailability.Raw | null;
         audiences: string[];

diff --git a/...ges/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/IdempotencyHeader.ts b/...ges/cli/openapi-ir-sdk/src/sdk/serialization/resources/finalIr/types/IdempotencyHeader.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 IdempotencyHeader: core.serialization.ObjectSchema<
+    serializers.IdempotencyHeader.Raw,
+    FernOpenapiIr.IdempotencyHeader
+> = core.serialization.objectWithoutOptionalProperties({
+    header: core.serialization.string(),
+    name: core.serialization.string().optional(),
+    env: core.serialization.string().optional(),
+    schema: core.serialization.lazy(async () => (await import("../../..")).Schema).optional(),
+});
+
+export declare namespace IdempotencyHeader {
+    interface Raw {
+        header: string;
+        name?: string | null;
+        env?: string | null;
+        schema?: serializers.Schema.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
@@ -43,6 +43,9 @@ export const OpenApiIntermediateRepresentation: core.serialization.ObjectSchema<
     globalHeaders: core.serialization
         .list(core.serialization.lazyObject(async () => (await import("../../..")).GlobalHeader))
         .optional(),
+    idempotencyHeaders: core.serialization
+        .list(core.serialization.lazyObject(async () => (await import("../../..")).IdempotencyHeader))
+        .optional(),
 });
 
 export declare namespace OpenApiIntermediateRepresentation {
@@ -62,5 +65,6 @@ export declare namespace OpenApiIntermediateRepresentation {
         nonRequestReferencedSchemas: serializers.SchemaId.Raw[];
         securitySchemes: Record<serializers.SecuritySchemeId.Raw, serializers.SecurityScheme.Raw>;
         globalHeaders?: serializers.GlobalHeader.Raw[] | null;
+        idempotencyHeaders?: serializers.IdempotencyHeader.Raw[] | null;
     }
 }
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
@@ -1,6 +1,7 @@
 export * from "./OpenApiIntermediateRepresentation";
 export * from "./SdkGroupInfo";
 export * from "./GlobalHeader";
+export * from "./IdempotencyHeader";
 export * from "./Tags";
 export * from "./HttpError";
 export * from "./Webhook";

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
@@ -13,6 +13,7 @@ export const EndpointWithExample: core.serialization.ObjectSchema<
     .objectWithoutOptionalProperties({
         authed: core.serialization.boolean(),
         internal: core.serialization.boolean().optional(),
+        idempotent: core.serialization.boolean().optional(),
         method: core.serialization.lazy(async () => (await import("../../..")).HttpMethod),
         availability: core.serialization.lazy(async () => (await import("../../..")).EndpointAvailability).optional(),
         audiences: core.serialization.list(core.serialization.string()),
@@ -50,6 +51,7 @@ export declare namespace EndpointWithExample {
     interface Raw extends serializers.WithDescription.Raw {
         authed: boolean;
         internal?: boolean | null;
+        idempotent?: boolean | null;
         method: serializers.HttpMethod.Raw;
         availability?: serializers.EndpointAvailability.Raw | null;
         audiences: string[];

diff --git a/packages/cli/openapi-ir-to-fern/src/FernDefnitionBuilder.ts b/packages/cli/openapi-ir-to-fern/src/FernDefnitionBuilder.ts
@@ -16,6 +16,8 @@ export interface FernDefinitionBuilder {
 
     addGlobalHeader({ name, schema }: { name: string; schema: RawSchemas.HttpHeaderSchema }): void;
 
+    addIdempotencyHeader({ name, schema }: { name: string; schema: RawSchemas.HttpHeaderSchema }): void;
+
     addVariable({ name, schema }: { name: string; schema: RawSchemas.VariableDeclarationSchema }): void;
 
     addEnvironment({ name, schema }: { name: string; schema: RawSchemas.EnvironmentSchema }): void;
@@ -179,6 +181,13 @@ export class FernDefinitionBuilderImpl implements FernDefinitionBuilder {
         this.rootApiFile.headers[name] = schema;
     }
 
+    public addIdempotencyHeader({ name, schema }: { name: string; schema: RawSchemas.HttpHeaderSchema }): void {
+        if (this.rootApiFile["idempotency-headers"] == null) {
+            this.rootApiFile["idempotency-headers"] = {};
+        }
+        this.rootApiFile["idempotency-headers"][name] = schema;
+    }
+
     public addVariable({ name, schema }: { name: string; schema: RawSchemas.VariableDeclarationSchema }): void {
         if (this.rootApiFile.variables == null) {
             this.rootApiFile.variables = {};

diff --git a/packages/cli/openapi-ir-to-fern/src/__test__/FernDefinitionBuilder.test.ts b/packages/cli/openapi-ir-to-fern/src/__test__/FernDefinitionBuilder.test.ts
@@ -21,6 +21,7 @@ describe("Fern Definition Builder", () => {
                 nonRequestReferencedSchemas: new Set(),
                 securitySchemes: {},
                 globalHeaders: [],
+                idempotencyHeaders: [],
                 groups: {},
                 channel: []
             },

diff --git a/...cli/openapi-ir-to-fern/src/__test__/__snapshots__/x-fern-idempotency-headers.test.ts.snap b/...cli/openapi-ir-to-fern/src/__test__/__snapshots__/x-fern-idempotency-headers.test.ts.snap
@@ -0,0 +1,127 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`x-fern-idempotency-headers x-fern-idempotency-headers docs 1`] = `
+{
+  "definitionFiles": {},
+  "packageMarkerFile": {
+    "service": {
+      "auth": false,
+      "base-path": "",
+      "endpoints": {
+        "send": {
+          "auth": false,
+          "docs": undefined,
+          "examples": [
+            {
+              "request": {},
+              "response": {
+                "body": "string",
+              },
+            },
+          ],
+          "idempotent": true,
+          "method": "POST",
+          "pagination": undefined,
+          "path": "/send",
+          "request": {
+            "body": {
+              "properties": {
+                "send": {
+                  "audiences": [
+                    "public",
+                  ],
+                  "docs": undefined,
+                  "type": "optional<boolean>",
+                },
+              },
+            },
+            "headers": undefined,
+            "name": "SendRequest",
+            "query-parameters": undefined,
+          },
+          "response": {
+            "docs": "Success!",
+            "type": "string",
+          },
+        },
+      },
+    },
+  },
+  "rootApiFile": {
+    "display-name": "Test extension \`x-fern-audiences\` alongside \`x-fern-streaming\`.",
+    "error-discrimination": {
+      "strategy": "status-code",
+    },
+    "idempotency-headers": {
+      "Idempotency-Key": {
+        "name": "idempotencyKey",
+        "type": "optional<string>",
+      },
+    },
+    "name": "api",
+  },
+}
+`;
+
+exports[`x-fern-idempotency-headers x-fern-idempotency-headers simple 1`] = `
+{
+  "definitionFiles": {},
+  "packageMarkerFile": {
+    "service": {
+      "auth": false,
+      "base-path": "",
+      "endpoints": {
+        "send": {
+          "auth": false,
+          "docs": undefined,
+          "examples": [
+            {
+              "request": {},
+              "response": {
+                "body": "string",
+              },
+            },
+          ],
+          "idempotent": true,
+          "method": "POST",
+          "pagination": undefined,
+          "path": "/send",
+          "request": {
+            "body": {
+              "properties": {
+                "send": {
+                  "audiences": [
+                    "public",
+                  ],
+                  "docs": undefined,
+                  "type": "optional<boolean>",
+                },
+              },
+            },
+            "headers": undefined,
+            "name": "SendRequest",
+            "query-parameters": undefined,
+          },
+          "response": {
+            "docs": "Success!",
+            "type": "string",
+          },
+        },
+      },
+    },
+  },
+  "rootApiFile": {
+    "display-name": "Test extension \`x-fern-audiences\` alongside \`x-fern-streaming\`.",
+    "error-discrimination": {
+      "strategy": "status-code",
+    },
+    "idempotency-headers": {
+      "Idempotency-Key": {
+        "name": "idempotencyKey",
+        "type": "optional<string>",
+      },
+    },
+    "name": "api",
+  },
+}
+`;
diff --git a/packages/cli/openapi-ir-to-fern/src/__test__/fixtures/x-fern-idempotency-headers/openapi.yml b/packages/cli/openapi-ir-to-fern/src/__test__/fixtures/x-fern-idempotency-headers/openapi.yml
@@ -0,0 +1,29 @@
+openapi: 3.1.0
+info:
+  title: Test extension `x-fern-audiences` alongside `x-fern-streaming`.
+  version: 1.0.0
+x-fern-idempotency-headers:
+  - header: Idempotency-Key
+paths:
+  "/send":
+    post:
+      x-fern-sdk-method-name: send
+      x-fern-idempotent: true
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                send:
+                  type: boolean
+                  x-fern-audiences: [ "public" ]
+      responses:
+        "200":
+          description: "Success!"
+          content:
+            application/json:
+              schema:
+                type: string
+components:
+  schemas: {}
diff --git a/packages/cli/openapi-ir-to-fern/src/__test__/x-fern-idempotency-headers.test.ts b/packages/cli/openapi-ir-to-fern/src/__test__/x-fern-idempotency-headers.test.ts
@@ -0,0 +1,5 @@
+import { testConvertOpenAPI } from "./testConvertOpenApi";
+
+describe("x-fern-idempotency-headers", () => {
+    testConvertOpenAPI("x-fern-idempotency-headers", "openapi.yml");
+});
diff --git a/packages/cli/openapi-ir-to-fern/src/buildEndpoint.ts b/packages/cli/openapi-ir-to-fern/src/buildEndpoint.ts
@@ -209,6 +209,10 @@ export function buildEndpoint({
         }
     }
 
+    if (endpoint.idempotent) {
+        convertedEndpoint.idempotent = true;
+    }
+
     if (endpoint.availability === EndpointAvailability.Beta) {
         convertedEndpoint.availability = "pre-release";
     } else if (endpoint.availability === EndpointAvailability.GenerallyAvailable) {

diff --git a/packages/cli/openapi-ir-to-fern/src/buildFernDefinition.ts b/packages/cli/openapi-ir-to-fern/src/buildFernDefinition.ts
@@ -5,6 +5,7 @@ import { buildAuthSchemes } from "./buildAuthSchemes";
 import { buildChannel } from "./buildChannel";
 import { buildEnvironments } from "./buildEnvironments";
 import { buildGlobalHeaders } from "./buildGlobalHeaders";
+import { buildIdempotencyHeaders } from "./buildIdempotencyHeaders";
 import { buildServices } from "./buildServices";
 import { buildTypeDeclaration } from "./buildTypeDeclaration";
 import { buildVariables } from "./buildVariables";
@@ -22,6 +23,7 @@ export const ERROR_DECLARATIONS_FILENAME = RelativeFilePath.of(FERN_PACKAGE_MARK
 export function buildFernDefinition(context: OpenApiIrConverterContext): FernDefinition {
     buildEnvironments(context);
     buildGlobalHeaders(context);
+    buildIdempotencyHeaders(context);
     buildAuthSchemes(context);
     buildVariables(context);
     if (context.ir.basePath != null) {