【亲测免费】 Docusaurus OpenAPI 文档生成插件指南

本指南旨在帮助您了解并使用 docusaurus-openapi-docs 开源项目，它是一款强大的工具，能够将OpenAPI规范转换为Docusaurus支持的MDX格式文档，以优雅的方式展示API参考信息。

1. 项目目录结构及介绍

当您克隆这个项目后，典型的基本目录结构如下：

├── docusaurus.config.js 或 docusaurus.config.ts   <- 配置文件
├── examples                  <- 示例OpenAPI规格文件所在目录
├── packages                  <- 插件和主题相关代码可能位于此
├── src                       <- 可能包含自定义组件或脚本
├── themes                    <- 主题相关代码，包括docusaurus-theme-openapi-docs
├── docs                      <- 自动生成的API文档存放地（由插件生成）
├── .gitignore                <- 忽略文件列表
├── README.md                 <- 项目主读我文件
├── package.json              <- 项目依赖和scripts命令
└── other necessary files    <- 如LICENSE, CONTRIBUTING.md等其他文档

• docusaurus.config 文件是项目的核心配置，包含了插件的设置。
• examples 目录通常用于存放示例的OpenAPI规格文件，供测试和演示使用。
• src 和 themes 分别存放自定义的前端代码和特定主题的样式及逻辑。
• docs 是生成的API文档默认存放位置，由插件根据OpenAPI规范自动生成。

2. 项目的启动文件介绍

项目启动主要通过以下命令进行管理，重点在于使用npm或yarn执行Docusaurus提供的命令，而不是项目内部特定的“启动文件”。在标准的Docusaurus项目中，关键的启动操作通常是通过以下命令实现的：

• 初始化和启动服务:

  yarn start
  

  这个命令将会启动开发服务器，让你可以预览站点。

• 构建静态站点:

  yarn build
  

  用于生产环境的站点构建，生成静态HTML文件。

• 生成API文档（基于docusaurus-openapi-docs）:

  根据项目文档的指示，可能会有特定的插件命令来生成或更新API文档，但具体命令需查看项目中的scripts部分或者docusaurus.config.js中的插件配置。

3. 项目的配置文件介绍

docusaurus.config.js 或 docusaurus.config.ts

这是配置插件的关键。配置示例如下：

module.exports = {
  // 省略其他非插件相关配置...
  plugins: [
    ['docusaurus-plugin-openapi-docs', {
      id: "api",
      docsPluginId: "classic", // 对于默认Docusaurus配置
      config: {
        petstore: { // 假设这是一个API规范命名
          specPath: "examples/petstore.yaml", // OpenAPI规范的路径
          outputDir: "docs/api", // 输出文档的目录
          // ...其他配置项
        },
      },
    }],
  ],
  themes: ["docusaurus-theme-openapi-docs"], // 使用的主题
};

• plugins 部分添加了docusaurus-plugin-openapi-docs，其中可以指定多个API规范配置。
• specPath 指向你的OpenAPI规范文件的位置。
• outputDir 定义生成的文档存放路径。
• config 中还可以包含更详细的选项，如版本控制、侧边栏配置等，详细配置需参考项目文档。

记住，实际配置可能更为复杂，依据您的具体需求调整上述模板。务必查阅项目的最新README文件，获取最精确的配置指导和命令说明。