From 6f4bfffe0aeb7f0f12ddd8018a8ef3de3765e12d Mon Sep 17 00:00:00 2001 From: "val.istar.guo" Date: Sun, 2 Jun 2024 21:25:01 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0opendoc=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...72\347\241\200\345\212\237\350\203\275.md" | 51 ++++++++++++------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git "a/docs/2.\345\237\272\347\241\200\345\212\237\350\203\275.md" "b/docs/2.\345\237\272\347\241\200\345\212\237\350\203\275.md" index 2cdb7c8..095bb51 100644 --- "a/docs/2.\345\237\272\347\241\200\345\212\237\350\203\275.md" +++ "b/docs/2.\345\237\272\347\241\200\345\212\237\350\203\275.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,7 +61,7 @@ async function main() { }, // 文档配置 - apiDocuments: [ + sheets: [ { // 文档类型 目前支持三种 'asyncapi' | 'openapi' | 'markdown' type: 'openapi' @@ -61,10 +69,17 @@ async function main() { code: 'my_document_code', // 文档间的排序 order: 1 - // 文档文件内容 + + // AsyncAPI 和 OpenAPI 可以直接上传文件内容 file: JSON.stringify({ // Openapi/swagger }) + // AsyncAPI 和 OpenAPI也也可以指定文件路径 + filepath: 'openapi/swagger filepath' + + // Markdown需要通过glob表达式匹配上传的文件列表 + glob: 'docs/**/*.md' + } ] })