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

package/README.md

@@ -0,0 +1,80 @@
+# api-doc
+
+English | [中文](./README.zh-CN.md)
+
+
+## Introduction
+
+This plugin is based on `swagger` to write documentation.
+
+## How to access the documentation
+
+1. The access address in the plugin center is `{domain}/admin/settings/api-doc/documentation`
+2. The access address outside the plugin center is `{domain}/api-documentation`
+
+## How to write swagger documentation
+
+> The method in the plugin is the same
+
+1. `src/swagger.{ts,json}`
+2. `src/swagger/index.{ts,json}`
+
+The file paths above can all be traversed to write documentation. Just export your written documentation by default. An example is shown below:
+
+```ts
+export default {
+  info: {
+    title: 'NocoBase API - Api-doc plugin',
+  },
+  tags: [],
+  paths: {},
+  components: {
+    schemas: {}
+  }
+};
+```
+
+Usually, you only need to write **info.title**, **tags**, **paths**, and **components**. Other information such as **server** and **info** are merged into our **base-swagger**.
+
+Base swagger includes the following code:
+
+```ts
+// base swagger
+export 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/',
+  },
+  components: {
+    securitySchemes: {
+      'api-key': {
+        type: 'http',
+        scheme: 'bearer',
+      },
+    },
+  },
+  security: [
+    {
+      'api-key': [],
+    },
+  ],
+};
+```
+
+> Note that configurations that can only be obtained at runtime, such as the server and version fields, are not filled in the base-swagger.
+
+You can also override these defaults. When writing the swagger documentation for your plugin, you should consider whether your plugin's documentation can be accessed independently.
+
+For detailed swagger writing rules, please refer to the [official documentation](https://swagger.io/docs/specification/about/).

package/README.zh-CN.md

@@ -0,0 +1,79 @@
+# api-doc
+
+[English](./README.md) | 中文
+
+## 简介
+
+该插件基于 `swagger` 编写文档。
+
+## 如何访问文档
+
+1. 在插件中心访问地址是 `{domain}/admin/settings/api-doc/documentation`
+2. 在插件中心外访问地址是 `{domain}/api-documentation`
+
+## 如何编写 swagger 文档
+
+> 插件内方式一样
+
+1. `src/swagger.{ts,json}`
+2. `src/swagger/index.{ts,json}`
+
+上面的文件路径均可遍写文档，只需最后将您编写的文档默认导出即可，例子如下：
+
+```ts
+export default {
+  info: {
+    title: 'NocoBase API - Auth plugin',
+  },
+  tags: [],
+  paths: {},
+  components: {
+    schemas: {}
+  }
+};
+```
+
+通常你只需要编写 **info.title**, **tags**, **paths**, **components** 即可其他内容如 **server**, **info** 的其他信息都合并我们的 **base-swagger**.
+
+base swagger 包含如下代码
+```ts
+// base swagger
+export 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/',
+  },
+  components: {
+    securitySchemes: {
+      'api-key': {
+        type: 'http',
+        scheme: 'bearer',
+      },
+    },
+  },
+  security: [
+    {
+      'api-key': [],
+    },
+  ],
+};
+
+```
+
+> 注意：涉及到运行时才能获取的配置，并没有填写在 base-swagger 里，如 server, version 字段
+
+这些默认的配置你同样也可以覆盖它，在你编写插件的 `swagger` 文档时，你需要视你的插件文档是独立的文档，可以被单独访问。
+
+详细的 `swagger` 编写规则请参考[官方文档](https://swagger.io/docs/specification/about/)

package/client.d.ts

@@ -0,0 +1,2 @@
+export * from './dist/client';
+export { default } from './dist/client';

package/client.js

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

package/dist/client/Document.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import 'swagger-ui-dist/swagger-ui.css';
+declare const Documentation: () => React.JSX.Element;
+export default Documentation;

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+import { Plugin } from '@nocobase/client';
+export declare const useStyles: (props?: unknown) => import("antd-style").ReturnStyles<import("antd-style").SerializedStyles>;
+export declare class APIDocumentationPlugin extends Plugin {
+    load(): Promise<void>;
+}
+export default APIDocumentationPlugin;