Mark Google media downloads as binary responses (#1096)

Author: batumilove

packages/plugins/google/src/sdk/discovery.test.ts

@@ -274,6 +274,64 @@ it.effect("converts Google Discovery documents into Executor-preserving OpenAPI
   }),
 );
 
+it.effect("marks Google Discovery media-download methods as binary responses", () =>
+  Effect.gen(function* () {
+    const result = yield* convertGoogleDiscoveryToOpenApi({
+      discoveryUrl: "https://www.googleapis.com/discovery/v1/apis/drive/v3/rest",
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
+      documentText: JSON.stringify({
+        name: "drive",
+        version: "v3",
+        title: "Drive API",
+        rootUrl: "https://www.googleapis.com/",
+        servicePath: "drive/v3/",
+        resources: {
+          files: {
+            methods: {
+              export: {
+                id: "drive.files.export",
+                httpMethod: "GET",
+                path: "files/{fileId}/export",
+                supportsMediaDownload: true,
+                useMediaDownloadService: true,
+                parameters: {
+                  fileId: { location: "path", required: true, type: "string" },
+                  mimeType: { location: "query", required: true, type: "string" },
+                },
+              },
+            },
+          },
+        },
+        schemas: {},
+      }),
+    });
+
+    const spec = decodeConvertedSpec(result.specText);
+    const operation = spec.paths["/files/{fileId}/export"]?.get;
+    expect(operation?.responses).toMatchObject({
+      "200": {
+        content: {
+          "application/octet-stream": {
+            schema: { type: "string", format: "binary" },
+          },
+        },
+      },
+    });
+
+    const parsed = yield* parse(result.specText);
+    const extracted = yield* extract(parsed);
+    const exportOperation = extracted.operations.find(
+      (candidate) => candidate.operationId === "files.export",
+    );
+    expect(exportOperation?.operationId).toBe("files.export");
+    const responseFileHint = Option.flatMap(
+      exportOperation?.responseBody ?? Option.none(),
+      (body) => body.fileHint,
+    );
+    expect(Option.isSome(responseFileHint)).toBe(true);
+  }),
+);
+
 it.effect("bundles Google Discovery documents into one Google OpenAPI source", () =>
   Effect.gen(function* () {
     const result = yield* convertGoogleDiscoveryBundleToOpenApi({

packages/plugins/google/src/sdk/discovery.ts

@@ -76,11 +76,12 @@ type OpenApiOperationObject = {
   readonly responses: {
     readonly "200": {
       readonly description: "Successful response";
-      readonly content: {
-        readonly "application/json": {
+      readonly content: Record<
+        string,
+        {
           readonly schema: OpenApiSchemaObject;
-        };
-      };
+        }
+      >;
     };
   };
   readonly security?: readonly Record<string, readonly string[]>[];
@@ -174,6 +175,8 @@ const DiscoveryMethod = Schema.Struct({
   request: Schema.optional(DiscoveryRef),
   response: Schema.optional(DiscoveryRef),
   scopes: TextArray,
+  supportsMediaDownload: Schema.optional(Schema.Boolean),
+  useMediaDownloadService: Schema.optional(Schema.Boolean),
 });
 type DiscoveryMethod = typeof DiscoveryMethod.Type;
 
@@ -570,6 +573,33 @@ const discoveryDocumentInfo = (
     };
   });
 
+const googleDiscoveryResponseContent = (
+  method: DiscoveryMethod,
+  schemaNameForRef: (name: string) => string,
+): OpenApiOperationObject["responses"]["200"]["content"] => {
+  if (
+    (method.supportsMediaDownload === true || method.useMediaDownloadService === true) &&
+    method.response === undefined
+  ) {
+    return {
+      "application/octet-stream": {
+        schema: {
+          type: "string",
+          format: "binary",
+        },
+      },
+    };
+  }
+
+  return {
+    "application/json": {
+      schema: method.response?.$ref
+        ? { $ref: schemaRef(schemaNameForRef(method.response.$ref)) }
+        : {},
+    },
+  };
+};
+
 const buildDiscoveryOperation = (input: {
   readonly document: DiscoveryDocument;
   readonly method: DiscoveryMethod;
@@ -635,13 +665,7 @@ const buildDiscoveryOperation = (input: {
     responses: {
       "200": {
         description: "Successful response",
-        content: {
-          "application/json": {
-            schema: input.method.response?.$ref
-              ? { $ref: schemaRef(schemaNameForRef(input.method.response.$ref)) }
-              : {},
-          },
-        },
+        content: googleDiscoveryResponseContent(input.method, schemaNameForRef),
       },
     },
     ...(methodScopes.length > 0 ? { security: [{ googleOAuth2: methodScopes }] } : {}),