added support to save openapi spec to disk

Signed-off-by: Noorain Panjwani <[email protected]>

Author: YourTechBud

.eslintrc.json

@@ -24,10 +24,7 @@
     "@typescript-eslint/semi": "error",
     "@typescript-eslint/no-var-requires": "error",
     "@typescript-eslint/member-delimiter-style": "error",
-    "quotes": [
-      "error",
-      "double"
-    ],
+    "quotes": ["error", "double"],
     "@typescript-eslint/no-unused-vars": [
       "error",
       {

.gitignore

@@ -128,3 +128,8 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+# Autogenerated config files
+openapi.json
+openapi.yaml
+sc.yaml

README.md

@@ -3,7 +3,7 @@ Typescript API for Space Cloud
 
 ## Worker API
 
-Sample usage
+### Sample usage
 ```ts
 import { Server } from "@spacecloud-io/worker";
 import { z } from "zod";
@@ -21,7 +21,7 @@ const router = server.router();
 // Register a query object.
 router.query("operate")                       // `opId` is the name of the operation
   .method("GET")                              // Defaults to `GET` for queries and `POST` for mutations
-  .url("/v1/operate")                         // Defaults to `${baseURL}/${opId}`                                                 
+  .url("/v1/operate")                         // Defaults to `${baseUrl}/${opId}`                                                 
   .input(z.object({ name: z.string() }))
   .output(z.object({ greeting: z.string() }))
   .fn(async (_ctx, req) => {
@@ -30,4 +30,19 @@ router.query("operate")                       // `opId` is the name of the opera
 
 // Start the express http server.
 server.start();
+```
+
+The worker generates the some additional routes as shown below:
+
+```
+# Routes created to expose the OpenAPI specification generated
+[GET] `${baseUrl}/openapi.json`
+[GET] `${baseUrl}/openapi.yaml` 
+```
+
+### Saving OpenAPI specification to disk
+
+Simply add the flag `--save-openapi` flag to save the autogenerated Open API specification in yaml format. Use the `-f, --file <path>` flag to control the file path. The specification will be persisted at `${file}/openapi.yaml`.
+```
+node index.js --save-openapi -f ./config
 ```

package.json

@@ -6,6 +6,7 @@
   "main": "index.js",
   "scripts": {
     "build:worker": "pnpm --filter worker run build",
+    "build:basic": "pnpm --filter basic run build",
     "dev:worker": "pnpm --filter worker run dev",
     "dev:basic": "pnpm --filter basic run dev",
     "start:basic": "pnpm --filter basic run start"

packages/worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacecloud-io/worker",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,8 +13,10 @@
   "author": "Noorain Panjwani <[email protected]>",
   "license": "Apache-2.0",
   "dependencies": {
+    "commander": "^11.0.0",
     "express": "^4.18.2",
     "openapi3-ts": "^4.1.2",
+    "yaml": "^2.3.2",
     "zod": "^3.21.4",
     "zod-to-json-schema": "^3.21.1"
   },

packages/worker/src/config.ts

@@ -0,0 +1,21 @@
+import fs from "fs";
+import { stringify } from "yaml";
+
+export const generateSCConfigFile = (path: string, spec: any) => {
+    const data = stringify(spec);
+    fs.writeFileSync(path, data);
+};
+
+export const createOpenApiSpec = (spec: any, name: string, port: number) => {
+    return {
+        apiVersion: "core.space-cloud.io/v1alpha1",
+        kind: "OpenAPISource",
+        metadata: {
+            name: name
+        },
+        spec: {
+            source: { url: `http://localhost:${port}` },
+            openapi: { value: spec }
+        }
+    };
+};

packages/worker/src/helpers.ts

@@ -1,6 +1,36 @@
 import { Request } from "express";
 import openapi3 from "openapi3-ts/oas30";
 
+export const getOpenApiParametersFromJsonSchema = (schema: any) => {
+  let params: openapi3.ParameterObject[] = [];
+
+  for (const key in schema.properties) {
+    const paramType = schema.properties[key].type;
+    switch (paramType) {
+      case "string":
+      case "number":
+      case "integer":
+      case "boolean":
+        params = [...params, {
+          in: "query",
+          name: key,
+          schema: { type: paramType },
+        }];
+        break;
+
+      default:
+        params = [...params, {
+          in: "query",
+          name: key,
+          content: { "application/json": { schema: schema.properties[key] } },
+        }];
+        break;
+    }
+  }
+
+  return params;
+};
+
 export const getPayloadFromParams = (query: any, inputSchema: any) => {
   // Return the payload as is if type is any or additional property is set to true
   if (inputSchema.type === undefined || inputSchema.additionalProperties) return query;

packages/worker/src/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import openapi3 from "openapi3-ts/oas30";
 
-import { getErrorResponseSchema, getPayloadFromParams, isZodTypeNull, processException } from "./helpers";
+import { getErrorResponseSchema, getOpenApiParametersFromJsonSchema, getPayloadFromParams, isZodTypeNull, processException } from "./helpers";
 import { Context } from "./context";
 
 export type RouteUpdater = (r: Route<any, any>) => void;
@@ -118,18 +118,38 @@ export class Route<I, O> {
   }
 
   public _getOpenAPIOperation() {
-    // Process request schema
-    const isRequestNull = isZodTypeNull(this.config.zodSchemas.input);
-    const requestBodyObject: openapi3.RequestBodyObject = {
-      description: `Request object for ${this.config.opId}`,
-      content: {},
-      required: false
+    // First create a operation
+    const operation: openapi3.OperationObject = {
+      operationId: this.config.opId,
+      responses: {
+        "400": getErrorResponseSchema(),
+        "401": getErrorResponseSchema(),
+        "403": getErrorResponseSchema(),
+        "500": getErrorResponseSchema(),
+      },
+
+      // Add the sc specific extensions
+      ["x-request-op-type"]: this.config.opType,
     };
 
-    // Add request schema if we require payload
+    // Process request schema
+    const isRequestNull = isZodTypeNull(this.config.zodSchemas.input);
     if (!isRequestNull) {
-      requestBodyObject.content = { "application/json": { schema: this.config.jsonSchema.input } };
-      requestBodyObject.required = true;
+      switch (this.config.method) {
+        case "get":
+        case "delete":
+          operation.parameters = getOpenApiParametersFromJsonSchema(this.config.jsonSchema.input);
+          break;
+
+        default:
+          // Add request body if we require payload
+          operation.requestBody = {
+            description: `Request object for ${this.config.opId}`,
+            content: { "application/json": { schema: this.config.jsonSchema.input } },
+            required: true
+          };
+          break;
+      }
     }
 
     // Process response schemas
@@ -141,21 +161,7 @@ export class Route<I, O> {
     if (!isResponseNull) {
       successResponseObject.content = { "application/json": { schema: this.config.jsonSchema.output } };
     }
-
-
-    // Add the schemas to operation
-    const operation: openapi3.OperationObject = {
-      operationId: this.config.opId,
-      requestBody: requestBodyObject,
-      responses: {
-        [successResponseStatusCode]: successResponseObject,
-        "400": getErrorResponseSchema(),
-        "500": getErrorResponseSchema(),
-      },
-
-      // Add the sc specific extensions
-      ["x-request-op-type"]: this.config.opType,
-    };
+    operation.responses[successResponseStatusCode] = successResponseObject;
 
     return {
       path: this.config.url,

packages/worker/src/router.ts

@@ -12,10 +12,12 @@ export interface RouterConfig {
 export class Router {
   private config: RouterConfig;
   private routes: Route<any, any>[];
+  openApiBuilder: openapi3.OpenApiBuilder;
 
   constructor(config: RouterConfig) {
     this.config = config;
     this.routes = [];
+    this.openApiBuilder = openapi3.OpenApiBuilder.create();
   }
 
   /**
@@ -82,23 +84,28 @@ export class Router {
     return route;
   }
 
-  _initialiseRoutes(app: express.Application) {
+  _generateOpenApi() {
     // Create the open api document
-    const builder = openapi3.OpenApiBuilder.create();
-    builder.addTitle(this.config.name);
+    this.openApiBuilder.addTitle(this.config.name);
 
     // Add one path for each operation
     this.routes.forEach(route => {
       // Get OpenAPI operation for route
       const { path, method, operation } = route._getOpenAPIOperation();
 
       // Add path to OpenAPI spec
-      builder.addPath(path, { [method]: operation });
+      this.openApiBuilder.addPath(path, { [method]: operation });
     });
+  }
 
+  _getOpenApiSpec() {
+    return this.openApiBuilder.getSpec();
+  }
+
+  _initialiseRoutes(app: express.Application) {
     // Add express routes for openapi doc
-    const jsonSpec = builder.getSpecAsJson();
-    const yamlSpec = builder.getSpecAsYaml();
+    const jsonSpec = this.openApiBuilder.getSpecAsJson();
+    const yamlSpec = this.openApiBuilder.getSpecAsYaml();
     app.get(`${this.config.baseUrl}/openapi.json`, (_req, res) => {
       res.setHeader("Content-Type", "application/json");
       res.status(200).send(jsonSpec);

packages/worker/src/server.ts

@@ -1,5 +1,7 @@
 import express, { Application } from "express";
+import { Command } from "commander";
 import { Router } from "./router";
+import { generateSCConfigFile } from "./config";
 
 export interface ServerConfig {
   name: string;
@@ -11,16 +13,31 @@ export class Server {
   private config: ServerConfig;
   private app: express.Application;
   private routerObj: Router;
+  private program: Command;
 
   public constructor(config: ServerConfig) {
-    // Set default values if not provided
-    if (!config.baseUrl) config.baseUrl = "/v1";
-    if (!config.port) config.port = 3000;
 
     // Initialise the server object
     this.config = config;
-    this.routerObj = new Router({ name: config.name, baseUrl: config.baseUrl });
+
+    // Set default values if not provided
+    if (!this.config.baseUrl) this.config.baseUrl = "/v1";
+    if (!this.config.port) this.config.port = 3000;
+
+    // Create a router object
+    this.routerObj = new Router({ name: this.config.name, baseUrl: this.config.baseUrl });
+
+    // Create an express app
     this.app = express();
+
+    // Create an a commander object
+    this.program = new Command();
+    this.program
+      .name(this.config.name)
+      .description(`"${this.config.name}" is a SpaceCloud worker`);
+
+    this.program.option("--save-openapi", "Save the autogenerated OpenAPI configuration", false);
+    this.program.option("-f, --file <path>", "File path to store the configuration.", ".");
   }
 
   /**
@@ -49,7 +66,23 @@ export class Server {
    * It also exposes the OpenAPI spec for this server on `${baseUrl}/openapi.json`.
    */
   public start() {
-    // First add the global middlewares we need
+    // Generate the open api spec for the app
+    this.routerObj._generateOpenApi();
+
+    // Parse the commands passed
+    this.program.parse();
+    const options = this.program.opts();
+
+    // Check if the `--save-openapi` flag has been provided
+    if (options["saveOpenapi"]) {
+      const path = `${options["file"]}/openapi.yaml`;
+      console.log(`Generating OpenAPI file at path - "${path}"`);
+      generateSCConfigFile(path, this.routerObj._getOpenApiSpec());
+      console.log("Open API configuration has been successfully saved!");
+      return;
+    }
+
+    // Then add the global middlewares we need
     this.app.use(express.json());
 
     // Add a default route