更新opendoc文档

docs/2.基础功能.md

@@ -5,28 +5,34 @@
 
 [OpenDOC](https://github.com/buka-lnc/app.opendoc) 是一款开源的接口文档平台。支持[OpenAPI][openapi]和[AsyncAPI][asyncapi]规范。接下来我将为你详细介绍 OpenDoc 的核心概念。
 
-## 应用（Application）
+## Application(应用)
 
-Opendoc 的一个应用可以添加多个文档。
-应用必须设置唯一的`code`标识，`code`标识在 SDK、应用/文档注册等功能中发挥重要作用。
+Opendoc 的一个 Application 可以承载多种不同类型的文档，全方面的描述 Application 的功能。
+并且，Application 必须设置唯一的`code`标识。
 
-> 应用`id`由于难以记忆，往往并不会使用。
+## Sheet(页签)
 
-## 文档（Document）
+每个 Application 中可以创建任意多个 Sheet。
+Sheet 也需要设置 Application 下唯一的`code`标识。
+每个 Sheet 都可以添加多份相同类型的 ApiDocument。
+Sheet 的支持的类型如下：
 
-文档是对于应用的接口/功能的描述性文件。目前支持的格式有：
+| Type     | Description                                                                                                                        |
+| :------- | :--------------------------------------------------------------------------------------------------------------------------------- |
+| Markdown | 描述应用程序的单个文本文件。支持多份 markdown 格式的文件组成目录树                                                                 |
+| OpenAPI  | 描述应用的 Http 接口文档。 仅支持一份 swagger 格式的 json ，文件必须被命名为 `openapi.json`                                        |
+| AsyncAPI | 描述应用使用其他中间件实现的接口，例如：Kafka、RabbitMQ 等。仅支持一份 asyncapi 格式的 json 文件，文件必须被命名为 `asyncapi.json` |
 
-- OpenAPI（也成为 Swagger）：常被用做描述应用的 Http 接口
-- AsyncAPI：常被用于描述应用使用其他中间件实现的接口，例如：Kafka、RabbitMQ 等。
-- Markdown：描述应用程序的单个纯文本文件。
+虽然每个 Sheet 都可以添加多份 ApiDocument，但由于 Openapi 和 Asyncapi 规范都只需要有一个 json 文件，
+这两个类型的 Sheet 如果添加约定外的 ApiDocument 将无法在页面上展示。
 
-文档必须设定一个在应用下唯一的`code`。在 SDK 和文档注册等中也有很重要的作用。
+## ApiDocument(文件)
 
-文档并不推荐一次性添加，而是建议采用 Push 或 Pull 模式保持文档与应用的持续更新。
+ApiDocument 并不推荐一次性添加，而是建议采用 Push 或 Pull 模式保持文档与应用的持续更新。
 
 ### Pull 模式
 
-当我们将一个文档设定为 Pull 模式并配置**同步地址**后，
+当我们将一个 Sheet 设定为 Pull 模式并配置**同步地址**后，
 OpenDoc 会定期的请求**同步地址**获取最新的文档内容，
 一旦文档内容与上一版本文档内容不一致，
 OpenDoc 将会自动添加一个新版本的文档。
@@ -36,15 +42,17 @@ OpenDoc 将会自动添加一个新版本的文档。
 Push 模式下，文档的更新来自于*外部程序*调用 OpenDoc 的接口。
 当*外部程序*提供的文档数据与上一个版本不一致时，OpenDoc 会添加一个新版本的文档。
 
-OpenDoc 官方提供了`@opendoc/register`包以便 NodeJS 接入 OpenDoc 的 Push 模式：
+OpenDoc 官方提供了`@opendoc/register`包，以便 NodeJS 接入 OpenDoc 的 Push 模式：
 
 ```typescript
-import { registerToOpendoc } from '@opendoc/register'
+import { register } from '@opendoc/register'
 
 async function main() {
-  await registerToOpendoc({
+  await register({
     // OpenDoc 地址
-    server: 'http://localhost:8080',
+    server: {
+      origin: 'http://localhost:8080',
+    },
 
     // 应用配置，如果应用不存在会自动创建
     application: {
@@ -53,18 +61,25 @@ async function main() {
     },
 
     // 文档配置
-    apiDocuments: [
+    sheets: [
       {
         // 文档类型 目前支持三种 'asyncapi' | 'openapi' | 'markdown'
         type: 'openapi'
         title?: 'MyDocumentDisplayName'
         code: 'my_document_code',
         // 文档间的排序
         order: 1
-        // 文档文件内容
+
+        // AsyncAPI 和 OpenAPI 可以直接上传文件内容
         file: JSON.stringify({
           // Openapi/swagger
         })
+        // AsyncAPI 和 OpenAPI也也可以指定文件路径
+        filepath: 'openapi/swagger filepath'
+
+        // Markdown需要通过glob表达式匹配上传的文件列表
+        glob: 'docs/**/*.md'
+
       }
     ]
   })