mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
47738ceea4
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
227 lines
9.8 KiB
Plaintext
227 lines
9.8 KiB
Plaintext
---
|
||
title: "SDK 参考设置"
|
||
description: "了解如何使用 TypeDoc、DocFX、Javadoc、Sphinx 或 phpDocumentor 的构建产物，在 Mintlify 中自动生成 SDK 参考页面、导航分组、跨页链接和搜索索引，并通过 CI 或远程源保持内容更新。本文还介绍格式配置、目录路径、远程压缩包和仓库组织方式。"
|
||
keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"]
|
||
---
|
||
|
||
使用 `sdk` 导航属性，可以基于你已经在使用的文档工具，为 SDK 库生成参考页面。Mintlify 会读取每个工具生成的构建产物，为每个 class、interface、module 和 function 创建一个页面，并自动生成导航分组、跨页链接与搜索索引。
|
||
|
||
<div id="supported-formats">
|
||
## 支持的格式
|
||
</div>
|
||
|
||
| `format` | Tool | Artifact |
|
||
| --- | --- | --- |
|
||
| `typedoc` | [TypeDoc](https://typedoc.org) (TypeScript/JavaScript) | JSON 导出文件 |
|
||
| `docfx` | [DocFX](https://dotnet.github.io/docfx/) (.NET) | `docfx metadata` 输出目录 (ManagedReference YAML) |
|
||
| `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | 标准 doclet HTML 目录 |
|
||
| `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | JSON builder 输出目录 |
|
||
| `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | `structure.xml` 文件 |
|
||
|
||
<div id="generate-an-artifact">
|
||
## 生成构建产物
|
||
</div>
|
||
|
||
以机器可读的输出格式运行你的文档工具。如果你已经在 CI 中发布生成的文档，通常只需在同一命令中添加一个参数即可。
|
||
|
||
<CodeGroup>
|
||
|
||
```bash TypeDoc
|
||
npx typedoc --json typedoc.json src/index.ts
|
||
```
|
||
|
||
```bash DocFX
|
||
docfx metadata docfx.json
|
||
```
|
||
|
||
```bash Javadoc
|
||
javadoc -d javadoc-output -sourcepath src/main/java -subpackages com.example
|
||
# Or download the published javadoc jar from Maven Central
|
||
```
|
||
|
||
```bash Sphinx
|
||
python -m sphinx -b json docs/source artifacts/json
|
||
```
|
||
|
||
```bash phpDocumentor
|
||
phpdoc -d src -t artifacts --template=xml
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<div id="auto-populate-sdk-pages">
|
||
## 自动填充 SDK 页面
|
||
</div>
|
||
|
||
在 `docs.json` 的某个 tab 或 group 中添加 `sdk` 属性。Mintlify 会解析该构建产物，并为该库创建导航分组和页面。
|
||
|
||
```json
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "SDK Reference",
|
||
"sdk": {
|
||
"format": "typedoc",
|
||
"source": "sdk-artifacts/typedoc.json",
|
||
"directory": "sdk/typescript"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
在 group 上添加 `sdk`，即可只在 tab 的某一部分生成页面，而不是占用整个 tab。Group 和页面会继承其父级 tab 或 group 的 `sdk` 设置。如果嵌套的 group 定义了自己的 `sdk`，Mintlify 会使用该设置，而不是继承的设置。
|
||
|
||
```json
|
||
{
|
||
"group": "TypeScript SDK",
|
||
"sdk": {
|
||
"format": "typedoc",
|
||
"source": "sdk-artifacts/typedoc.json",
|
||
"directory": "sdk/typescript"
|
||
},
|
||
"pages": ["sdk/typescript/overview"]
|
||
}
|
||
```
|
||
|
||
包含 `sdk` 的 group 也可以列出你自己编写的 `pages`。你的页面会显示在前面，生成的参考分组紧随其后。
|
||
|
||
<Note>
|
||
你可以在 [tab](/zh/organize/navigation#tabs) 或 [group](/zh/organize/navigation#groups) 上声明 `sdk`。
|
||
|
||
- 包含 `sdk` 的 tab 可以包含 `groups`，但不能包含其他导航结构，例如 `pages`、`versions` 或 `languages`，也不能包含 `openapi`、`asyncapi` 或 `graphql` 属性。
|
||
- 包含 `sdk` 的 group 可以包含 `pages` 和嵌套的 group，但不能包含 `graphql` 属性。
|
||
</Note>
|
||
|
||
<ParamField path="format" type="string" required>
|
||
用于生成构建产物的文档工具：`typedoc`、`docfx`、`javadoc`、`sphinx` 或 `phpdoc`。
|
||
</ParamField>
|
||
|
||
<ParamField path="source" type="string" required>
|
||
指向文档仓库中构建产物文件或目录的相对路径，或者一个 HTTPS URL。不接受 HTTP URL。
|
||
</ParamField>
|
||
|
||
<ParamField path="directory" type="string">
|
||
生成页面的 URL 路径前缀。默认值为 `sdk-reference`。
|
||
</ParamField>
|
||
|
||
添加多个 tab 或 group 即可为多个库生成文档。例如，在同一个 tab 中使用两个 group，分别对应某个 SDK 的稳定版和 beta 版。为每个库使用唯一的 `directory`，以避免路由冲突。
|
||
|
||
<Tip>
|
||
将你的构建产物目录添加到 [`.mintignore`](/zh/organize/mintignore)，让 Mintlify 将这些产物视为构建输入，而不是将其发布为静态资源。
|
||
</Tip>
|
||
|
||
<div id="generated-pages">
|
||
## 生成的页面
|
||
</div>
|
||
|
||
Mintlify 会将生成的导航组添加到 tab 中已有的任何 `groups` 之后。如果你在 group 上添加了 `sdk`，生成的分组会显示在该 group 的 `pages` 之后。这些组因格式而异，可能表示模块、包、命名空间或符号类型。
|
||
|
||
每个生成的页面都记录了构建产物中的一个类、接口、函数、类型或其他符号，并链接到相关的生成页面。如果转换器生成的页面不属于任何组，Mintlify 会将它们归入 `Reference` 组。
|
||
|
||
<div id="customize-a-page-for-a-single-symbol">
|
||
## 为单个符号自定义页面
|
||
</div>
|
||
|
||
在 MDX 页面上使用 `sdk` frontmatter，可将构建产物中的某个符号作为目标。Mintlify 会先渲染你编写的任何正文内容，然后在其下方追加该符号对应的生成参考内容。当你希望在某个特定的 class、interface 或 method 之上添加示例、迁移说明或上下文时，可以使用这种方式。
|
||
|
||
像其他页面一样，将该页面添加到 `docs.json` 的导航中。Mintlify 只会为出现在导航中的页面生成 SDK 内容。
|
||
|
||
当包含 `sdk` 的 tab 或 group 中存在带有 `sdk` frontmatter 的页面时，Mintlify 会停止自动填充该 tab 或 group，只显示你编写的页面。如果你希望该库的其余部分继续自动填充，请将该页面移到该 tab 或 group 之外。
|
||
|
||
让 `sdk` 指向某个符号：
|
||
|
||
```mdx
|
||
---
|
||
title: "Client"
|
||
sdk: "class Client"
|
||
---
|
||
|
||
创建一个 `Client` 来调用 API。
|
||
```
|
||
|
||
字符串形式遵循 `[source] kind name` 的模式。如果省略 `source`，页面会从 tab 或 group 的 `sdk` 配置继承。字符串形式始终继承 `format`，因此只能用于带有 `sdk` 的 tab 或 group 下的页面。其他情况下，请将 `sdk` 设置为包含下述字段的对象。对于 method 和 property，请包含父级名称，例如 `method Client.getUser`。
|
||
|
||
如果省略 `title` 或 `description`，Mintlify 会使用为该符号生成的标题和描述。
|
||
|
||
<ParamField path="kind" type="string" required>
|
||
符号类型：`class`、`interface`、`enum`、`function`、`type`、`variable`、`method` 或 `property`。
|
||
</ParamField>
|
||
|
||
<ParamField path="name" type="string" required>
|
||
符号名称，需与构建产物中出现的名称一致。
|
||
</ParamField>
|
||
|
||
<ParamField path="parent" type="string">
|
||
对 `method` 和 `property` 目标为必填。所属的 class、interface 或 type。
|
||
</ParamField>
|
||
|
||
<ParamField path="format" type="string">
|
||
覆盖继承的 `format`。当页面不属于带有 `sdk` 的 tab 或 group 时为必填。仅在对象形式中可用。
|
||
</ParamField>
|
||
|
||
<ParamField path="source" type="string">
|
||
覆盖继承的 `source`。当页面不属于带有 `sdk` 的 tab 或 group 时为必填。
|
||
</ParamField>
|
||
|
||
<div id="use-remote-sources">
|
||
## 使用远程源
|
||
</div>
|
||
|
||
将 `source` 设置为 HTTPS URL，即可在构建时获取构建产物，而无需将其提交到文档仓库中。
|
||
|
||
单文件格式（`typedoc`、`phpdoc`）可直接接受文件 URL。目录格式（`docfx`、`javadoc`、`sphinx`）接受 `zip` 压缩包。发布到 Maven Central 的 Javadoc jar 无需重新打包即可使用：
|
||
|
||
```json
|
||
{
|
||
"tab": "Java SDK",
|
||
"sdk": {
|
||
"format": "javadoc",
|
||
"source": "https://repo1.maven.org/maven2/com/example/my-library/1.0.0/my-library-1.0.0-javadoc.jar",
|
||
"directory": "sdk/java"
|
||
}
|
||
}
|
||
```
|
||
|
||
远程构建产物的下载大小上限为 50 MB，解压后大小上限为 200 MB。
|
||
|
||
<div id="keep-references-up-to-date">
|
||
## 保持参考文档最新
|
||
</div>
|
||
|
||
在你的 SDK 发生变化后，重新生成构建产物。常见做法是在每个 SDK 仓库中设置 CI 任务，在发布时运行文档工具。该任务可以将构建产物提交到文档仓库，或上传到 `source` 所指向的稳定 URL。
|
||
|
||
<div id="repository-setup">
|
||
## 仓库设置
|
||
</div>
|
||
|
||
在同一仓库或不同仓库中存储 SDK 代码和文档。选择符合你工作方式的模式。这两种方式支持相同的功能。
|
||
|
||
<div id="sdk-and-documentation-in-the-same-repository">
|
||
### SDK 和文档位于同一仓库
|
||
</div>
|
||
|
||
在与文档相同的仓库中生成 SDK 构建产物，并将 `source` 指向其相对路径。任何在 push 或 release 时生成构建产物的工作流都可以将其提交回仓库，并在下一次文档站点部署时发布更新。
|
||
|
||
```txt
|
||
docs-repo/
|
||
docs.json
|
||
content/
|
||
sdk-artifacts/
|
||
typedoc.json
|
||
```
|
||
|
||
<div id="sdk-in-a-separate-repository">
|
||
### SDK 位于单独的仓库
|
||
</div>
|
||
|
||
当 SDK 位于自己的仓库中时，有两种方式。
|
||
|
||
1. **将构建产物提交到文档仓库。** 在 SDK 仓库中设置一个在发布时运行的 CI 任务。该任务生成构建产物，并向文档仓库发起拉取请求（或推送提交），其中包含更新后的文件。将此更改合并到部署分支以触发站点部署。将 `source` 指向已提交的路径，与单仓库设置相同。
|
||
|
||
2. **托管构建产物并在构建时获取。** 将构建产物上传到稳定的 HTTPS URL，例如 S3 存储桶、GitHub Releases 资源或 Maven Central 上的 Javadoc jar。将 `source` 设置为该 URL。每次更新构建产物时，触发文档站点部署以获取新构建产物。发布构建产物后，从 SDK 发布流水线调用[触发部署](/zh/api/update/trigger)端点。
|
||
|
||
<Tip>
|
||
如果你的发布节奏较慢，或者希望文档仓库作为事实来源，请将构建产物提交到文档仓库。对于发布频繁、构建产物较大，或已发布构建产物（例如 Maven Central 上的 Javadoc jar）的情况，则应托管构建产物并在构建时获取。
|
||
</Tip>
|