Allow to publish an OpenAPI spec from URL (#785)

Author: gregberge

.changeset/good-penguins-clap.md

@@ -0,0 +1,5 @@
+---
+'@gitbook/cli': patch
+---
+
+Allow to publish an OpenAPI spec from URL

packages/cli/src/cli.ts

@@ -3,6 +3,7 @@
 import checkNodeVersion from 'check-node-version';
 import { program } from 'commander';
 import * as path from 'path';
+import { URL } from 'url';
 import prompts from 'prompts';
 
 import { GITBOOK_DEFAULT_ENDPOINT } from '@gitbook/api';
@@ -15,7 +16,11 @@ import { publishIntegration, unpublishIntegration } from './publish';
 import { authenticate, whoami } from './remote';
 import { tailLogs } from './tail';
 import { checkIntegrationBuild } from './check';
-import { publishOpenAPISpecification } from 'openapi/publish';
+import {
+    publishOpenAPISpecificationFromFilepath,
+    publishOpenAPISpecificationFromURL,
+} from 'openapi/publish';
+import { checkIsHTTPURL } from './util';
 
 program
     .name(Object.keys(packageJSON.bin)[0])
@@ -120,16 +125,22 @@ const openAPIProgram = program.command('openapi').description('manage OpenAPI sp
 
 openAPIProgram
     .command('publish')
-    .description('publish an OpenAPI specification')
-    .argument('<file>', 'OpenAPI specification file path')
+    .description('publish an OpenAPI specification from a file or URL')
+    .argument('<file-or-url>', 'OpenAPI specification file path or URL')
     .requiredOption('-s, --spec <spec>', 'name of the OpenAPI specification')
     .requiredOption('-o, --organization <organization>', 'organization to publish to')
-    .action(async (filepath, options) => {
-        const spec = await publishOpenAPISpecification({
-            specSlug: options.spec,
-            specFilepath: path.resolve(process.cwd(), filepath),
-            organizationId: options.organization,
-        });
+    .action(async (filepathOrURL, options) => {
+        const spec = checkIsHTTPURL(filepathOrURL)
+            ? await publishOpenAPISpecificationFromURL({
+                  specSlug: options.spec,
+                  organizationId: options.organization,
+                  url: filepathOrURL,
+              })
+            : await publishOpenAPISpecificationFromFilepath({
+                  specSlug: options.spec,
+                  organizationId: options.organization,
+                  filepath: path.resolve(process.cwd(), filepathOrURL),
+              });
         console.log(`OpenAPI specification "${options.spec}" published to ${spec.urls.app}`);
     });
 

packages/cli/src/openapi/publish.ts

@@ -5,26 +5,56 @@ import * as api from '@gitbook/api';
 import { getAPIClient } from '../remote';
 
 /**
- * Publish an OpenAPI specification to GitBook.
+ * Publish an OpenAPI specification to GitBook from a URL.
  * If it already exists, it'll update it.
  */
-export async function publishOpenAPISpecification(args: {
+export async function publishOpenAPISpecificationFromURL(args: {
     /**
      * The slug of the OpenAPI specification.
      */
     specSlug: string;
     /**
-     * The path to the OpenAPI specification file.
+     * The organization to publish to.
+     */
+    organizationId: string;
+    /**
+     * The URL pointing to the OpenAPI specification.
      */
-    specFilepath: string;
+    url: string;
+}): Promise<api.OpenAPISpec> {
+    const api = await getAPIClient(true);
+    const spec = await api.orgs.createOrUpdateOpenApiSpecBySlug(
+        args.organizationId,
+        args.specSlug,
+        {
+            source: {
+                url: args.url,
+            },
+        },
+    );
+    return spec.data;
+}
 
+/**
+ * Publish an OpenAPI specification to GitBook from a file.
+ * If it already exists, it'll update it.
+ */
+export async function publishOpenAPISpecificationFromFilepath(args: {
+    /**
+     * The slug of the OpenAPI specification.
+     */
+    specSlug: string;
     /**
      * The organization to publish to.
      */
     organizationId: string;
+    /**
+     * The path to the OpenAPI specification file.
+     */
+    filepath: string;
 }): Promise<api.OpenAPISpec> {
     const api = await getAPIClient(true);
-    const fileContent = await readOpenAPIFile(args.specFilepath);
+    const fileContent = await readOpenAPIFile(args.filepath);
     const spec = await api.orgs.createOrUpdateOpenApiSpecBySlug(
         args.organizationId,
         args.specSlug,
@@ -37,6 +67,9 @@ export async function publishOpenAPISpecification(args: {
     return spec.data;
 }
 
+/**
+ * Read the OpenAPI specification file.
+ */
 async function readOpenAPIFile(filePath: string): Promise<string> {
     try {
         const fileContent = await fs.promises.readFile(filePath, 'utf8');

packages/cli/src/util.ts

@@ -0,0 +1,14 @@
+/**
+ * Check if a string is a valid HTTP URL
+ */
+export function checkIsHTTPURL(str: string): boolean {
+    if (!str.startsWith('http')) {
+        return false;
+    }
+    try {
+        new URL(str);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}