@lobb-js/core 0.13.0

package/src/api/openApiRoute.ts

@@ -0,0 +1,1017 @@
+import type { Context } from "hono";
+import type { OpenAPIV3_1 } from "openapi-types";
+
+import { Hono } from "hono";
+import { apiReference } from "@scalar/hono-api-reference";
+import { LobbError } from "../LobbError.ts";
+import { metaRoutePathDescription } from "./meta/route.ts";
+import _ from "lodash";
+import { Lobb } from "../Lobb.ts";
+
+export function getOpenApiRoute() {
+  const route = new Hono();
+  const config = Lobb.instance.configManager.config;
+  const apiReferenceAsAny = apiReference as any;
+
+  route.get(
+    "/",
+    (c: Context) => {
+      const schema: OpenAPIV3_1.Document = {
+        openapi: "3.1.0",
+        info: config.project.info as any,
+        servers: config.project.servers,
+        tags: [
+          {
+            name: "meta",
+            description: "Meta data of the lobb API",
+          },
+          ...generateCollectionsTags(),
+        ],
+        components: generateCollectionsComponents(),
+        paths: generatePaths(),
+      };
+      return c.json(schema);
+    },
+  );
+
+  route.get(
+    "/ui",
+    apiReferenceAsAny({
+      theme: "saturn",
+      spec: {
+        url: "/api/openapi",
+      },
+    }),
+  );
+
+  return route;
+}
+
+function generateCollectionsTags() {
+  const tags: {
+    name: string;
+    description: string;
+  }[] = [];
+  const collectionConfig = Lobb.instance.configManager.getCollections();
+  for (const [collectionName, collection] of Object.entries(collectionConfig)) {
+    tags.push({
+      name: collectionName,
+      description: (collection as any).description,
+    });
+  }
+
+  return tags;
+}
+
+function generateCollectionsComponents() {
+  const components: any = {
+    schemas: {},
+  };
+  const collectionConfig = Lobb.instance.configManager.getCollections();
+  for (const [collectionName, collection] of Object.entries(collectionConfig)) {
+    components.schemas[collectionName] = {
+      type: "object",
+      properties: {},
+    };
+    for (
+      const [fieldName, field] of Object.entries((collection as any).fields)
+    ) {
+      components.schemas[collectionName]["properties"][fieldName] =
+        generateModelProperty(field);
+    }
+  }
+
+  components.schemas["internalErrorReponse"] = {
+    type: "object",
+    properties: {
+      status: {
+        type: "integer",
+        example: 500,
+      },
+      code: {
+        type: "string",
+        example: "INTERNAL_ERROR",
+      },
+      message: {
+        type: "string",
+        example: "An unexpected error occurred. Please contact support.",
+      },
+    },
+  };
+
+  const extensionSystem = Lobb.instance.extensionSystem;
+  components.schemas = {
+    ...components.schemas,
+    ...extensionSystem.getExtensionsOpenApiComponents(),
+  };
+
+  return components;
+}
+
+function generatePaths() {
+  let paths: any = {};
+  const collectionConfig = Lobb.instance.configManager.getCollections();
+  for (const [collectionName, collection] of Object.entries(collectionConfig)) {
+    paths[`/api/collections/${collectionName}/{id}`] = {
+      get: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Get a record`,
+        description: `Get a record from ${collectionName}`,
+        parameters: [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": `The record ID of ${collectionName}.`,
+            "schema": {
+              "type": "integer",
+              "example": 10,
+            },
+          },
+        ],
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      $ref: `#/components/schemas/${collectionName}`,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "400": {
+            description: "Bad Request",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 400,
+                    },
+                    code: {
+                      type: "string",
+                      example: "BAD_REQUEST",
+                    },
+                    message: {
+                      type: "string",
+                      example: "Invalid ID format",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "404": {
+            description: "Not found",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 404,
+                    },
+                    code: {
+                      type: "string",
+                      example: "NOT_FOUND",
+                    },
+                    message: {
+                      type: "string",
+                      example: "The record is not found",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+      patch: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Update a record`,
+        description: `Update an existing ${collectionName} by id`,
+        parameters: [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The record ID.",
+            "schema": {
+              "type": "integer",
+              "example": 10,
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  data: {
+                    required: true,
+                    $ref: `#/components/schemas/${collectionName}`,
+                  },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      $ref: `#/components/schemas/${collectionName}`,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "400": {
+            description: "Bad Request",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 400,
+                    },
+                    code: {
+                      type: "string",
+                      example: "INCOMPATIBLE_VALUE_TYPE",
+                    },
+                    message: {
+                      type: "string",
+                      example:
+                        "The value provided for the (published) field is incompatible.",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "403": {
+            description: "Forbidden",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 403,
+                    },
+                    code: {
+                      type: "string",
+                      example: "FORBIDDEN",
+                    },
+                    message: {
+                      type: "string",
+                      example: "Updating the ID proprety is not allowed.",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "404": {
+            description: "Not found",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 404,
+                    },
+                    code: {
+                      type: "string",
+                      example: "NOT_FOUND",
+                    },
+                    message: {
+                      type: "string",
+                      example: "The record is not found",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+      delete: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Delete a record`,
+        description: `Delete a record from ${collectionName}`,
+        parameters: [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The record ID.",
+            "schema": {
+              "type": "integer",
+              "example": 10,
+            },
+          },
+        ],
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      $ref: `#/components/schemas/${collectionName}`,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "400": {
+            description: "Bad Request",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 400,
+                    },
+                    code: {
+                      type: "string",
+                      example: "BAD_REQUEST",
+                    },
+                    message: {
+                      type: "string",
+                      example: "Invalid ID format",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "404": {
+            description: "Not found",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 404,
+                    },
+                    code: {
+                      type: "string",
+                      example: "NOT_FOUND",
+                    },
+                    message: {
+                      type: "string",
+                      example: "The record is not found",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    paths[`/api/collections/${collectionName}`] = {
+      post: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Create a record`,
+        description: `Add new record to ${collectionName}`,
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  data: {
+                    required: true,
+                    $ref: `#/components/schemas/${collectionName}`,
+                  },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          "201": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      $ref: `#/components/schemas/${collectionName}`,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "400": {
+            description: "Bad Request",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    status: {
+                      type: "integer",
+                      example: 400,
+                    },
+                    code: {
+                      type: "string",
+                      example: "INCOMPATIBLE_VALUE_TYPE",
+                    },
+                    message: {
+                      type: "string",
+                      example:
+                        "The value provided for the (published) field is incompatible.",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+      patch: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Update many records`,
+        description: `Update many records of ${collectionName}`,
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  filter: {
+                    required: true,
+                    type: "object",
+                    description: "Filter criteria object",
+                    example: {
+                      "published": {
+                        $eq: false,
+                      },
+                      "title": {
+                        $eq: "test",
+                      },
+                    },
+                  },
+                  data: {
+                    required: true,
+                    $ref: `#/components/schemas/${collectionName}`,
+                  },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    affectedCount: {
+                      type: "integer",
+                      example: 11,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+      delete: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Delete many records`,
+        description: `Delete many records of ${collectionName}`,
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  filter: {
+                    type: "object",
+                    description: "Filter criteria object",
+                    required: true,
+                    example: {
+                      "published": {
+                        $eq: false,
+                      },
+                      "title": {
+                        $eq: "test",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    affectedCount: {
+                      type: "integer",
+                      example: 11,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+      get: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Get many records`,
+        description: `Get many records of ${collectionName}`,
+        parameters: [
+          {
+            "name": "sort",
+            "in": "query",
+            "required": false,
+            "description":
+              "Fields to sort by, separated by commas. Use a minus sign ('-') for descending order. E.g., '-created_at,likes_count'",
+            "schema": {
+              "type": "string",
+              "example": "-created_at,likes_count",
+            },
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "The number of records to return",
+            "schema": {
+              "type": "integer",
+              "default": 100,
+              "example": 100,
+            },
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "description": "The number of records to skip (for pagination)",
+            "schema": {
+              "type": "integer",
+              "default": 0,
+              "example": 0,
+            },
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "The page number for pagination",
+            "schema": {
+              "type": "integer",
+              "example": 1,
+            },
+          },
+          {
+            "name": "fields",
+            "in": "query",
+            "required": false,
+            "description":
+              "Comma-separated list of fields to include in the response",
+            "schema": {
+              "type": "string",
+              "default": "*",
+              "example": "id,title,body",
+            },
+          },
+          {
+            "name": "filter",
+            "in": "query",
+            "required": false,
+            "description":
+              "Filter criteria object to apply to the records in a query string format",
+            "schema": {
+              "type": "object",
+              "example": "filter[published][$eq]=false&filter[title][$eq]=test",
+            },
+          },
+        ],
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        $ref: `#/components/schemas/${collectionName}`,
+                      },
+                    },
+                    meta: {
+                      type: "object",
+                      properties: {
+                        totalCount: {
+                          type: "integer",
+                          example: 10,
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    paths[`/api/collections/${collectionName}/search`] = {
+      post: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Get many records`,
+        description: `Get many records of ${collectionName}`,
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  sort: {
+                    type: "string",
+                    description:
+                      "Fields to sort by, separated by commas. Use a minus sign ('-') for descending order. E.g., '-created_at,likes_count'",
+                    example: "-created_at,likes_count",
+                  },
+                  limit: {
+                    type: "integer",
+                    description: "The number of records to return",
+                    default: 100,
+                    example: 100,
+                  },
+                  offset: {
+                    type: "integer",
+                    description:
+                      "The number of records to skip (for pagination)",
+                    default: 0,
+                    example: 0,
+                  },
+                  page: {
+                    type: "integer",
+                    description: "The page number for pagination",
+                    example: 1,
+                  },
+                  fields: {
+                    type: "string",
+                    description:
+                      "Comma-separated list of fields to include in the response",
+                    default: "*",
+                    example: "id,title,body",
+                  },
+                  filter: {
+                    type: "object",
+                    description: "Filter criteria object",
+                    example: {
+                      "published": {
+                        $eq: false,
+                      },
+                      "title": {
+                        $eq: "test",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          "200": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        $ref: `#/components/schemas/${collectionName}`,
+                      },
+                    },
+                    meta: {
+                      type: "object",
+                      properties: {
+                        totalCount: {
+                          type: "integer",
+                          example: 10,
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    paths[`/api/collections/${collectionName}/many`] = {
+      post: {
+        tags: [
+          collectionName,
+        ],
+        summary: `Create many records`,
+        description: `Create many records of ${collectionName}`,
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  data: {
+                    required: true,
+                    type: "array",
+                    items: {
+                      $ref: `#/components/schemas/${collectionName}`,
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          "201": {
+            description: "Successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    affectedCount: {
+                      type: "integer",
+                      example: 11,
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Internal Error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: `#/components/schemas/internalErrorReponse`,
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  // adding the meta paths
+  for (const [path, value] of Object.entries(metaRoutePathDescription)) {
+    paths[path] = value;
+  }
+
+  // adding the extensions paths
+  const extensionSystem = Lobb.instance.extensionSystem;
+  const extensionsPaths = extensionSystem.getExtensionsOpenApiPaths();
+  for (const [path, value] of Object.entries(extensionsPaths)) {
+    if (paths[path]) {
+      _.merge(paths[path], value);
+    } else {
+      paths[path] = value;
+    }
+  }
+
+  _.merge(paths, extensionsPaths);
+
+  // remove the null routes and the null methods from the paths object
+  for (const [path, pathValue] of Object.entries(paths)) {
+    if (pathValue === null || pathValue === undefined) {
+      delete paths[path];
+      continue;
+    }
+    for (const [methodName, methodValue] of Object.entries(pathValue)) {
+      if (methodValue === null) {
+        delete paths[path][methodName];
+        continue;
+      }
+    }
+  }
+
+  return paths;
+}
+
+function generateModelProperty(field: any) {
+  if (field.type === "string") {
+    return {
+      type: "string",
+      example: "example string",
+    };
+  } else if (field.type === "text") {
+    return {
+      type: "text",
+      example:
+        "Officia ad ad amet ex commodo consectetur exercitation minim ipsum laboris.",
+    };
+  } else if (field.type === "bool") {
+    return {
+      type: "boolean",
+      example: true,
+    };
+  } else if (field.type === "date") {
+    return {
+      type: "string",
+      format: "date",
+      example: "2025-03-17",
+    };
+  } else if (field.type === "datetime") {
+    return {
+      type: "string",
+      format: "date-time",
+      example: "2025-03-17T14:30:00Z",
+    };
+  } else if (field.type === "time") {
+    return {
+      type: "string",
+      format: "time",
+      example: "14:30:00",
+    };
+  } else if (field.type === "integer") {
+    return {
+      type: "integer",
+      format: "int32",
+      example: 10,
+    };
+  } else if (field.type === "long") {
+    return {
+      type: "integer",
+      format: "int64",
+      example: 100,
+    };
+  } else if (field.type === "float") {
+    return {
+      type: "number",
+      format: "float",
+      example: 10.1,
+    };
+  } else if (field.type === "decimal") {
+    return {
+      type: "number",
+      format: "double",
+      example: 10.01,
+    };
+  } else {
+    throw new LobbError({
+      code: "NOT_IMPLEMENTED",
+      message:
+        `The field type of (${field.type}) in openapi specs is not implemented`,
+    });
+  }
+}