@nocobase/plugin-api-doc 0.13.0-alpha.1

package/dist/server/swagger/index.d.ts

@@ -0,0 +1,48 @@
+import APIDocPlugin from '../server';
+export declare class SwaggerManager {
+    private plugin;
+    constructor(plugin: APIDocPlugin);
+    private get app();
+    private get db();
+    generateSwagger(options?: {
+        plugins?: string[];
+    }): Promise<unknown>;
+    getSwagger(): Promise<unknown>;
+    collection2Swagger(collectionName: string, withAssociation?: boolean): Promise<{
+        paths: any;
+        components: {
+            parameters: {};
+            schemas: {
+                [x: string]: {
+                    type: string;
+                    properties: {};
+                    allOf?: undefined;
+                } | {
+                    allOf: ({
+                        $ref: string;
+                        type?: undefined;
+                        properties?: undefined;
+                    } | {
+                        type: string;
+                        properties: any;
+                        $ref?: undefined;
+                    })[];
+                    type?: undefined;
+                    properties?: undefined;
+                };
+            };
+        };
+        tags: {
+            name: string;
+            description: any;
+        }[];
+    }>;
+    getCollectionsSwagger(name?: string): Promise<unknown>;
+    getPluginsSwagger(pluginName?: string): Promise<unknown>;
+    getCoreSwagger(): Promise<unknown>;
+    getUrls(): Promise<any[]>;
+    private getBaseSwagger;
+    private generateSchemas;
+    private generateCollectionBuiltInInterface;
+    private loadSwaggers;
+}

package/dist/server/swagger/index.js

@@ -0,0 +1,221 @@
+'use strict';
+
+var baseSwagger = require('./base-swagger');
+var constants = require('./constants');
+var helpers = require('./helpers');
+var loader = require('./loader');
+var merge = require('./merge');
+var collectionToSwaggerObject = require('./collections');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var baseSwagger__default = /*#__PURE__*/_interopDefault(baseSwagger);
+var collectionToSwaggerObject__default = /*#__PURE__*/_interopDefault(collectionToSwaggerObject);
+
+class SwaggerManager {
+  plugin;
+  constructor(plugin) {
+    this.plugin = plugin;
+  }
+  get app() {
+    return this.plugin.app;
+  }
+  get db() {
+    return this.plugin.db;
+  }
+  async generateSwagger(options = {}) {
+    const base = await this.getBaseSwagger();
+    const core = options.plugins ? {} : await loader.loadSwagger("@nocobase/server");
+    const plugins = await this.loadSwaggers(options.plugins);
+    return merge.merge(merge.merge(core, plugins), base);
+  }
+  async getSwagger() {
+    return this.generateSwagger();
+  }
+  async collection2Swagger(collectionName, withAssociation = true) {
+    const collection = this.db.getCollection(collectionName);
+    return await (async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      return collectionToSwaggerObject__default.default(collection, {
+        withAssociation
+      });
+    })();
+  }
+  async getCollectionsSwagger(name) {
+    const base = await this.getBaseSwagger();
+    let others = {};
+    if (name) {
+      const collectionSwagger = await this.collection2Swagger(name);
+      others = merge.merge(others, collectionSwagger);
+    } else {
+      const collections = await this.db.getRepository("collections").find({
+        filter: {
+          "name.$ne": ["roles", "users"],
+          "hidden.$isFalsy": true
+        }
+      });
+      for (const collection of collections) {
+        if (collection.name === "roles") {
+          continue;
+        }
+        try {
+          others = merge.merge(others, await this.collection2Swagger(collection.name, false));
+        } catch (e) {
+          this.app.log.error(e);
+        }
+      }
+    }
+    return merge.merge(base, others);
+  }
+  async getPluginsSwagger(pluginName) {
+    return this.generateSwagger({
+      plugins: pluginName ? [pluginName] : []
+    });
+  }
+  async getCoreSwagger() {
+    return merge.merge(await this.getBaseSwagger(), await loader.loadSwagger("@nocobase/server"));
+  }
+  async getUrls() {
+    const plugins = await loader.getPluginsSwagger(this.db).then((res) => {
+      return Object.keys(res).map((name) => {
+        var _a;
+        const schema = res[name];
+        return {
+          name: ((_a = schema.info) == null ? void 0 : _a.title) || name,
+          url: `/api/swagger:get?ns=${encodeURIComponent(`plugins/${name}`)}`
+        };
+      });
+    }).catch(() => []);
+    const collections = await this.db.getRepository("collections").find({
+      filter: {
+        "name.$ne": ["roles", "users"],
+        "hidden.$isFalsy": true
+      }
+    });
+    return [
+      {
+        name: "NocoBase API",
+        url: "/api/swagger:get"
+      },
+      {
+        name: "NocoBase API - Core",
+        url: "/api/swagger:get?ns=core"
+      },
+      {
+        name: "NocoBase API - All plugins",
+        url: "/api/swagger:get?ns=plugins"
+      },
+      {
+        name: "NocoBase API - Custom collections",
+        url: "/api/swagger:get?ns=collections"
+      },
+      ...plugins,
+      ...collections.map((collection) => {
+        return {
+          name: `Collection API - ${collection.title}`,
+          url: `/api/swagger:get?ns=${encodeURIComponent("collections/" + collection.name)}`
+        };
+      })
+    ];
+  }
+  async getBaseSwagger() {
+    return merge.merge(baseSwagger__default.default, {
+      info: {
+        version: await this.app.version.get()
+      },
+      servers: [
+        {
+          url: (this.app.resourcer.options.prefix || "/").replace(/^[^/]/, "/$1")
+        }
+      ]
+    });
+  }
+  generateSchemas() {
+    const schemas = {};
+    this.app.i18n;
+    this.db.collections.forEach((collection) => {
+      const properties = {};
+      const model = {
+        type: "object",
+        properties
+      };
+      collection.forEachField((field) => {
+        const { type, target } = field;
+        const property = {};
+        if (type === "hasMany" || type === "belongsToMany") {
+          property["type"] = "array";
+          property["items"] = {
+            $ref: `#/components/schemas/${target}`
+          };
+        } else if (type === "belongsTo" || type === "hasOne") {
+          property["type"] = "object";
+          property["$ref"] = `#/components/schemas/${target}`;
+        } else {
+          property.type = constants.SchemaTypeMapping[type] || type;
+          if (property.type === "array" && !property.items) {
+            property.items = {
+              type: "object"
+            };
+          }
+          property.example = field.get("defaultValue");
+        }
+        properties[field.name] = property;
+      });
+      schemas[collection.name] = model;
+    });
+    return schemas;
+  }
+  generateCollectionBuiltInInterface() {
+    const paths = {};
+    const IC = helpers.getInterfaceCollection(this.app.resourcer.options);
+    this.db.collections.forEach((collection) => {
+      const { name } = collection;
+      let actions;
+      if (this.app.resourcer.isDefined(name)) {
+        actions = this.app.resourcer.getResource(name).actions;
+      } else {
+        actions = {
+          has: () => true
+        };
+      }
+      const collectionMethods = {};
+      Object.entries(IC).forEach(([path, actionNames]) => {
+        actionNames.forEach((actionName) => {
+          const actionMethods = helpers.createDefaultActionSwagger({
+            collection
+          });
+          const { method = "post", ...swaggerArgs } = actionMethods[actionName];
+          const parameters = [];
+          ["associatedName", "associatedIndex", "resourceIndex"].forEach((name2) => {
+            if (path.includes(`{${name2}}`)) {
+              parameters.push({
+                name: name2,
+                required: true,
+                schema: {
+                  type: "string"
+                }
+              });
+            }
+          });
+          if (actions.has(actionName)) {
+            collectionMethods[path.replace("{resourceName}", `${name}:${actionName}`)] = {
+              [method]: {
+                tags: [name],
+                description: `${name}:${actionName}`,
+                parameters,
+                ...swaggerArgs
+              }
+            };
+          }
+        });
+      });
+      Object.assign(paths, collectionMethods);
+    });
+    return paths;
+  }
+  loadSwaggers(plugins) {
+    return loader.getSwaggerDocument(this.db, plugins);
+  }
+}
+
+exports.SwaggerManager = SwaggerManager;

package/dist/server/swagger/loader.d.ts

@@ -0,0 +1,4 @@
+export declare const loadSwagger: (packageName: string) => any;
+export declare const getPluginsSwagger: (db: any, pluginNames?: string[]) => Promise<{}>;
+export declare const mergeObjects: (objs: any[]) => any;
+export declare const getSwaggerDocument: (db: any, pluginNames?: string[]) => Promise<any>;

package/dist/server/swagger/loader.js

@@ -0,0 +1,54 @@
+'use strict';
+
+var server = require('@nocobase/server');
+var utils = require('@nocobase/utils');
+var merge = require('./merge');
+
+const loadSwagger = (packageName) => {
+  const prefixes = ["src", "lib", "dist"];
+  const targets = ["swagger.json", "swagger/index.json", "swagger"];
+  for (const prefix of prefixes) {
+    for (const dict of targets) {
+      try {
+        const file = `${packageName}/${prefix}/${dict}`;
+        const filePath = require.resolve(file);
+        delete require.cache[filePath];
+        return utils.requireModule(file);
+      } catch (error) {
+      }
+    }
+  }
+  return {};
+};
+const getPluginsSwagger = async (db, pluginNames) => {
+  const nameFilter = (pluginNames == null ? void 0 : pluginNames.length) ? { name: { $in: pluginNames } } : {};
+  const plugins = await db.getRepository("applicationPlugins").find({
+    filter: {
+      enabled: true,
+      ...nameFilter
+    }
+  });
+  const swaggers = {};
+  for (const plugin of plugins) {
+    const packageName = server.PluginManager.getPackageName(plugin.get("name"));
+    const res = loadSwagger(packageName);
+    if (Object.keys(res).length) {
+      swaggers[plugin.get("name")] = res;
+    }
+  }
+  return swaggers;
+};
+const mergeObjects = (objs) => {
+  return objs.reduce((cur, obj) => {
+    return merge.merge(cur, obj);
+  }, {});
+};
+const getSwaggerDocument = async (db, pluginNames) => {
+  const swaggers = await getPluginsSwagger(db, pluginNames);
+  return mergeObjects(Object.values(swaggers));
+};
+
+exports.getPluginsSwagger = getPluginsSwagger;
+exports.getSwaggerDocument = getSwaggerDocument;
+exports.loadSwagger = loadSwagger;
+exports.mergeObjects = mergeObjects;

package/dist/server/swagger/merge.d.ts

@@ -0,0 +1 @@
+export declare function merge(obj1: any, obj2: any, opts?: any): unknown;

package/dist/server/swagger/merge.js

@@ -0,0 +1,13 @@
+'use strict';
+
+var utils = require('@nocobase/utils');
+
+const overwriteMerge = (destinationArray, sourceArray, options) => sourceArray.concat(destinationArray);
+function merge(obj1, obj2, opts) {
+  return utils.merge(obj1, obj2, {
+    arrayMerge: overwriteMerge,
+    ...opts
+  });
+}
+
+exports.merge = merge;

package/dist/swagger.d.ts

@@ -0,0 +1,43 @@
+declare const _default: {
+    info: {
+        title: string;
+    };
+    paths: {
+        '/swagger:getUrls': {
+            get: {
+                description: string;
+                tags: string[];
+                responses: {
+                    200: {
+                        description: string;
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    components: {
+        responses: {
+            SwaggerUrls: {
+                type: string;
+                items: {
+                    properties: {
+                        name: {
+                            type: string;
+                        };
+                        url: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+export default _default;

package/dist/swagger.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var swagger_default = {
+  info: {
+    title: "NocoBase API - API doc plugin"
+  },
+  paths: {
+    "/swagger:getUrls": {
+      get: {
+        description: "Get all api-doc destination",
+        tags: ["swagger"],
+        responses: {
+          200: {
+            description: "successful operation",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/responses/SwaggerUrls"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  components: {
+    responses: {
+      SwaggerUrls: {
+        type: "array",
+        items: {
+          properties: {
+            name: {
+              type: "string"
+            },
+            url: {
+              type: "string"
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+module.exports = swagger_default;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@nocobase/plugin-api-doc",
+  "version": "0.13.0-alpha.1",
+  "displayName": "API documentation",
+  "displayName.zh-CN": "API 文档",
+  "description": "",
+  "license": "AGPL-3.0",
+  "main": "./dist/server/index.js",
+  "types": "./dist/server/index.d.ts",
+  "devDependencies": {
+    "swagger-ui-dist": "^5.3.1"
+  },
+  "peerDependencies": {
+    "@nocobase/client": "0.x",
+    "@nocobase/database": "0.x",
+    "@nocobase/server": "0.x"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nocobase/nocobase.git",
+    "directory": "packages/plugins/api-doc"
+  },
+  "gitHead": "0ebd4e85a1b0b0d0943768ab6cb5c3d824562239"
+}

package/server.d.ts

@@ -0,0 +1,3 @@
+// @ts-nocheck
+export * from './dist/server';
+export { default } from './dist/server';

package/server.js

@@ -0,0 +1 @@
+module.exports = require('./dist/server/index.js');