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

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from './server';

package/dist/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+var server = require('./server');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var server__default = /*#__PURE__*/_interopDefault(server);
+
+
+
+module.exports = server__default.default;

package/dist/locale/en-US.d.ts

@@ -0,0 +1,2 @@
+declare const _default: {};
+export default _default;

package/dist/locale/en-US.js

@@ -0,0 +1,5 @@
+'use strict';
+
+var en_US_default = {};
+
+module.exports = en_US_default;

package/dist/locale/index.d.ts

@@ -0,0 +1,4 @@
+export declare const NAMESPACE = "api-doc";
+export declare function lang(key: string): string;
+export declare function generateNTemplate(key: string): string;
+export declare function useTranslation(): import("react-i18next").UseTranslationResponse<"api-doc", undefined>;

package/dist/locale/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+var client = require('@nocobase/client');
+var reactI18next = require('react-i18next');
+
+const NAMESPACE = "api-doc";
+function lang(key) {
+  return client.i18n.t(key, { ns: NAMESPACE });
+}
+function generateNTemplate(key) {
+  return `{{t('${key}', { ns: '${NAMESPACE}' })}}`;
+}
+function useTranslation() {
+  return reactI18next.useTranslation(NAMESPACE);
+}
+
+exports.NAMESPACE = NAMESPACE;
+exports.generateNTemplate = generateNTemplate;
+exports.lang = lang;
+exports.useTranslation = useTranslation;

package/dist/locale/zh-CN.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    'API documentation': string;
+    Documentation: string;
+    'Select a definition': string;
+};
+export default _default;

package/dist/locale/zh-CN.js

@@ -0,0 +1,9 @@
+'use strict';
+
+var zh_CN_default = {
+  "API documentation": "Api \u6587\u6863",
+  "Documentation": "\u6587\u6863",
+  "Select a definition": "\u9009\u62E9\u7AEF\u70B9"
+};
+
+module.exports = zh_CN_default;

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export { default } from './server';

package/dist/server/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+var server = require('./server');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var server__default = /*#__PURE__*/_interopDefault(server);
+
+
+
+module.exports = server__default.default;

package/dist/server/server.d.ts

@@ -0,0 +1,8 @@
+import { Plugin } from '@nocobase/server';
+import { SwaggerManager } from './swagger';
+export default class APIDoc extends Plugin {
+    swagger: SwaggerManager;
+    constructor(app: any, options: any);
+    beforeLoad(): void;
+    load(): Promise<void>;
+}

package/dist/server/server.js

@@ -0,0 +1,51 @@
+'use strict';
+
+var server = require('@nocobase/server');
+var swagger = require('./swagger');
+
+class APIDoc extends server.Plugin {
+  swagger;
+  constructor(app, options) {
+    super(app, options);
+    this.swagger = new swagger.SwaggerManager(this);
+  }
+  beforeLoad() {
+  }
+  async load() {
+    this.app.resource({
+      name: "swagger",
+      type: "single",
+      actions: {
+        getUrls: async (ctx, next) => {
+          ctx.body = await this.swagger.getUrls();
+          await next();
+        },
+        get: async (ctx, next) => {
+          ctx.withoutDataWrapping = true;
+          const { ns } = ctx.action.params;
+          if (!ns) {
+            ctx.body = await this.swagger.getSwagger();
+            return;
+          }
+          const [type, index] = ns.split("/");
+          if (type === "core") {
+            ctx.body = await this.swagger.getCoreSwagger();
+          } else if (type === "plugins") {
+            ctx.body = await this.swagger.getPluginsSwagger(index);
+          } else if (type === "collections") {
+            ctx.body = await this.swagger.getCollectionsSwagger(index);
+          }
+          await next();
+        }
+      },
+      only: ["get", "getUrls"]
+    });
+    this.app.acl.allow("swagger", ["get", "getUrls"], "loggedIn");
+    this.app.acl.registerSnippet({
+      name: ["pm", this.name, "documentation"].join("."),
+      actions: ["swagger:*"]
+    });
+  }
+}
+
+module.exports = APIDoc;

package/dist/server/swagger/base-swagger.d.ts

@@ -0,0 +1,49 @@
+declare const _default: {
+    openapi: string;
+    info: {
+        title: string;
+        description: string;
+        contact: {
+            url: string;
+        };
+        license: {
+            name: string;
+            url: string;
+        };
+    };
+    externalDocs: {
+        description: string;
+        url: string;
+    };
+    components: {
+        securitySchemes: {
+            'api-key': {
+                type: string;
+                scheme: string;
+            };
+        };
+        schemas: {
+            error: {
+                type: string;
+                properties: {
+                    errors: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                message: {
+                                    description: string;
+                                    type: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    security: {
+        'api-key': any[];
+    }[];
+};
+export default _default;

package/dist/server/swagger/base-swagger.js

@@ -0,0 +1,54 @@
+'use strict';
+
+var base_swagger_default = {
+  openapi: "3.0.3",
+  info: {
+    title: "NocoBase API documentation",
+    description: "",
+    contact: {
+      url: "https://github.com/nocobase/nocobase/issues"
+    },
+    license: {
+      name: "Core packages are Apache 2.0 & Plugins packages are AGPL 3.0 licensed.",
+      url: "https://github.com/nocobase/nocobase#license"
+    }
+  },
+  externalDocs: {
+    description: "Find out more about NocoBase",
+    url: "https://docs.nocobase.com/api/http"
+  },
+  components: {
+    securitySchemes: {
+      "api-key": {
+        type: "http",
+        scheme: "bearer"
+      }
+    },
+    schemas: {
+      error: {
+        type: "object",
+        properties: {
+          errors: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                message: {
+                  description: "\u9519\u8BEF\u4FE1\u606F",
+                  type: "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  security: [
+    {
+      "api-key": []
+    }
+  ]
+};
+
+module.exports = base_swagger_default;

package/dist/server/swagger/collections/components/field-type-map.d.ts

@@ -0,0 +1,22 @@
+import { Field } from '@nocobase/database';
+declare const fieldTypeMap: {
+    bigint: {
+        type: string;
+        format: string;
+    };
+    datetime: {
+        type: string;
+        format: string;
+    };
+    string: {
+        type: string;
+    };
+    text: {
+        type: string;
+    };
+    jsontype: {
+        type: string;
+    };
+};
+declare function getTypeByField(field: Field): any;
+export { fieldTypeMap, getTypeByField };

package/dist/server/swagger/collections/components/field-type-map.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const fieldTypeMap = {
+  bigint: {
+    type: "integer",
+    format: "int64"
+  },
+  datetime: {
+    type: "string",
+    format: "date-time"
+  },
+  string: {
+    type: "string"
+  },
+  text: {
+    type: "string"
+  },
+  jsontype: {
+    type: "string"
+  }
+};
+function getTypeByField(field) {
+  const fieldType = field.dataType.toString().toLowerCase();
+  const fieldAttributes = fieldTypeMap[fieldType];
+  if (!fieldAttributes) {
+    return {
+      type: "string"
+    };
+  }
+  return fieldAttributes;
+}
+
+exports.fieldTypeMap = fieldTypeMap;
+exports.getTypeByField = getTypeByField;

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

@@ -0,0 +1,24 @@
+import { Collection } from '@nocobase/database';
+declare const _default: (collection: Collection, options: any) => {
+    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;
+        };
+    };
+};
+export default _default;

package/dist/server/swagger/collections/components/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+var schemas = require('./schemas');
+var parameters = require('./parameters');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var schemas__default = /*#__PURE__*/_interopDefault(schemas);
+var parameters__default = /*#__PURE__*/_interopDefault(parameters);
+
+var components_default = (collection, options) => {
+  return {
+    ...schemas__default.default(collection, options),
+    ...parameters__default.default(collection)
+  };
+};
+
+module.exports = components_default;

package/dist/server/swagger/collections/components/parameters.d.ts

@@ -0,0 +1,5 @@
+import { Collection } from '@nocobase/database';
+declare const _default: (collection: Collection) => {
+    parameters: {};
+};
+export default _default;

package/dist/server/swagger/collections/components/parameters.js

@@ -0,0 +1,173 @@
+'use strict';
+
+var fieldTypeMap = require('./field-type-map');
+
+var parameters_default = (collection) => {
+  const primaryKey = collection.model.primaryKeyAttribute;
+  const parameters = {};
+  if (primaryKey) {
+    const primaryKeyField = collection.fields.get(primaryKey);
+    if (!primaryKeyField) {
+      throw new Error(`primaryKeyField not found: ${primaryKey}, ${collection.name}`);
+    }
+    Object.assign(parameters, {
+      collectionIndex: {
+        required: true,
+        name: "collectionIndex",
+        in: "path",
+        description: "collection index",
+        schema: fieldTypeMap.getTypeByField(collection.fields.get(primaryKey))
+      },
+      filterByTk: {
+        name: "filterByTk",
+        in: "query",
+        description: "filter by TK(default by ID)",
+        schema: fieldTypeMap.getTypeByField(collection.fields.get(primaryKey))
+      },
+      filterByTks: {
+        name: "filterByTk",
+        in: "query",
+        description: "filter by TKs(default by ID), example: `1,2,3`",
+        schema: {
+          type: "array",
+          items: fieldTypeMap.getTypeByField(collection.fields.get(primaryKey))
+        }
+      }
+    });
+  }
+  Object.assign(parameters, {
+    filter: {
+      name: "filter",
+      in: "query",
+      description: "filter items",
+      schema: {
+        type: "object"
+      }
+    },
+    sort: {
+      name: "sort",
+      in: "query",
+      description: "sort items by fields, example: `-field1,-field2,field3`",
+      schema: {
+        oneOf: [
+          {
+            type: "array",
+            items: {
+              type: "string"
+            },
+            example: ["-id", "createdAt"]
+          },
+          {
+            type: "string",
+            example: "-id,createdAt"
+          }
+        ]
+      }
+    },
+    fields: {
+      name: "fields",
+      in: "query",
+      description: "select fields, example: `field1,field2`",
+      schema: {
+        oneOf: [
+          {
+            type: "array",
+            items: {
+              type: "string"
+            },
+            example: ["id", "createdAt"]
+          },
+          {
+            type: "string",
+            example: "id,createdAt"
+          }
+        ]
+      }
+    },
+    except: {
+      name: "except",
+      in: "query",
+      description: "except fields in results, example: `field1,field2`",
+      schema: {
+        oneOf: [
+          {
+            type: "array",
+            items: {
+              type: "string"
+            },
+            example: ["id", "createdAt"]
+          },
+          {
+            type: "string",
+            example: "id,createdAt"
+          }
+        ]
+      }
+    },
+    appends: {
+      name: "appends",
+      in: "query",
+      description: "append associations in results, example: `assoc1,assoc2`",
+      schema: {
+        oneOf: [
+          {
+            type: "array",
+            items: {
+              type: "string"
+            },
+            example: ["id", "createdAt"]
+          },
+          {
+            type: "string",
+            example: "id,createdAt"
+          }
+        ]
+      }
+    },
+    whitelist: {
+      name: "whitelist",
+      in: "query",
+      description: "whitelist for fields changes, example: `field1,field2`",
+      schema: {
+        oneOf: [
+          {
+            type: "array",
+            items: {
+              type: "string"
+            },
+            example: ["id", "createdAt"]
+          },
+          {
+            type: "string",
+            example: "id,createdAt"
+          }
+        ]
+      }
+    },
+    blacklist: {
+      name: "blacklist",
+      in: "query",
+      description: "blacklist for fields changes, example: `field1,field2`",
+      schema: {
+        oneOf: [
+          {
+            type: "array",
+            items: {
+              type: "string"
+            },
+            example: ["id", "createdAt"]
+          },
+          {
+            type: "string",
+            example: "id,createdAt"
+          }
+        ]
+      }
+    }
+  });
+  return {
+    parameters
+  };
+};
+
+module.exports = parameters_default;

package/dist/server/swagger/collections/components/schemas.d.ts

@@ -0,0 +1,23 @@
+import { Collection } from '@nocobase/database';
+declare const _default: (collection: Collection, options: any) => {
+    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;
+        };
+    };
+};
+export default _default;

package/dist/server/swagger/collections/components/schemas.js

@@ -0,0 +1,91 @@
+'use strict';
+
+var database = require('@nocobase/database');
+var fieldTypeMap = require('./field-type-map');
+var associations = require('../paths/associations');
+
+function getCollectionReadOnlyFields(collection) {
+  var _a;
+  const readOnlyFields = [];
+  const primaryKey = collection.model.primaryKeyAttribute;
+  if (primaryKey) {
+    const primaryField = collection.fields.get(primaryKey);
+    if (primaryField && ((_a = primaryField.options) == null ? void 0 : _a.autoIncrement)) {
+      readOnlyFields.push(primaryKey);
+    }
+  }
+  for (const [fieldName, field] of collection.fields) {
+    if (field.type == "sort") {
+      readOnlyFields.push(fieldName);
+      continue;
+    }
+    if (field.type == "context") {
+      readOnlyFields.push(fieldName);
+      continue;
+    }
+    if ([
+      "createdAt",
+      "updatedAt",
+      "created_at",
+      "updated_at",
+      "sort",
+      "created_by_id",
+      "createdById",
+      "updatedById",
+      "updated_by_id"
+    ].includes(fieldName)) {
+      readOnlyFields.push(fieldName);
+      continue;
+    }
+  }
+  return readOnlyFields;
+}
+function collectionToSchema(collection) {
+  return {
+    [collection.name]: {
+      type: "object",
+      properties: Array.from(collection.fields).filter(([key, value]) => {
+        return !(value instanceof database.RelationField);
+      }).reduce((obj, [key, value]) => {
+        obj[key] = {
+          ...getFieldTypeAttributes(value)
+        };
+        return obj;
+      }, {})
+    },
+    [`${collection.name}.form`]: {
+      allOf: [
+        {
+          $ref: `#/components/schemas/${collection.name}`
+        },
+        {
+          type: "object",
+          properties: getCollectionReadOnlyFields(collection).reduce((obj, key) => {
+            obj[key] = {
+              readOnly: true
+            };
+            return obj;
+          }, {})
+        }
+      ]
+    }
+  };
+}
+var schemas_default = (collection, options) => {
+  const associations$1 = associations.associationFields(collection);
+  const associationsTarget = associations$1.map((field) => collection.db.getCollection(field.target));
+  const schemas = collectionToSchema(collection);
+  if (options.withAssociation) {
+    for (const target of associationsTarget) {
+      Object.assign(schemas, collectionToSchema(target));
+    }
+  }
+  return {
+    schemas
+  };
+};
+function getFieldTypeAttributes(field) {
+  return fieldTypeMap.getTypeByField(field);
+}
+
+module.exports = schemas_default;

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

@@ -0,0 +1,31 @@
+import { Collection } from '@nocobase/database';
+declare function collectionToSwaggerObject(collection: Collection, options: any): {
+    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;
+    }[];
+};
+export default collectionToSwaggerObject;