Docusaurus-OpenAPI 教程

本文档将指导您了解并使用 docusaurus-openapi 这一用于在 Docusaurus v3 中生成 API 参考文档的插件。

1. 项目目录结构及介绍

在克隆或安装 docusaurus-openapi 项目后，典型的目录结构如下：

├── .docusaurus
│   ├── ...
│   └── ...
├── static
│   └── ... （存放静态资源）
├── src
│   ├── components
│   │   └── ... （自定义Docusaurus组件）
│   ├── pages
│   │   └── ... （网站页面）
│   ├── themes
│   │   └── openapi-docs
│   │       └── ... （主题相关代码）
│   └── utils
│       └── ... （辅助工具函数）
├── package.json
├── yarn.lock
└── docusaurus.config.js

• .docusaurus：存储 Docusaurus 的配置和其他元数据。
• static：放置非源码控制的静态资产。
• src：
  • components：自定义 React 组件。
  • pages：网站的路由和页面内容。
  • themes/openapi-docs：该插件的主题部分。
  • utils：帮助脚本和通用功能。
• package.json：项目依赖和脚本。
• docusaurus.config.js：Docusaurus 配置文件，用于设置站点的参数。

2. 项目启动文件介绍

项目的主要入口点是通过运行以下命令来启动的：

yarn start

这个命令会启动开发服务器，使您可以在本地查看和测试文档网站。当您编辑文件时，页面会自动刷新以显示更新的内容。

如果要构建生产环境版本，可以执行：

yarn build

这会产生一个可以在生产环境中部署的优化过的静态网站。

3. 项目的配置文件介绍

docusaurus.config.js 文件是 Docusaurus 的核心配置，其中包含了站点的各种设置，例如：

module.exports = {
  title: 'My API Docs', // 网站标题
  tagline: 'Awesome API documentation', // 标语
  url: 'http://localhost:3000', // 站点URL
  baseUrl: '/', // 应用的基础路径
  onBrokenLinks: 'throw', // 处理断链的方式
  onBrokenMarkdownLinks: 'warn', // 处理Markdown断链的方式
  favicon: 'img/favicon.ico', // Favicon路径
  organizationName: 'cloud-annotations', // GitHub 组织名称
  projectName: 'docusaurus-openapi', // GitHub 项目名称
  plugins: [
    [
      'docusaurus-plugin-openapi',
      {
        // 插件配置
        multiple: true,
        path: './openapi.yaml', // OpenAPI 规范文件路径
        id: 'my-api',
      },
    ],
  ],
  // 更多配置...
};

在这个文件中，您可以调整 Docusaurus 的行为，比如添加插件（如 docusaurus-plugin-openapi），定制主题，设置站点元数据等。对于 docusaurus-plugin-openapi 配置，您可以指定 OpenAPI 文档的位置以及它在站点中的唯一标识符。

希望这些信息对您理解和使用 docusaurus-openapi 插件有所帮助。如果有更多具体问题，欢迎继续提问。