在 Strapi v4 中生成专业 API 文档

引言：为什么需要 API 文档？

在现代 API 开发中，文档不仅是开发者的参考手册，更是团队协作和前后端联调的桥梁。Strapi 作为领先的开源无头 CMS，提供了强大的 API 文档生成功能。本文将详细介绍如何在 MacbookPro M1环境下，为 Strapi v4 项目配置和使用 API 文档功能。

环境准备：关键版本说明

组件	版本	重要性
Node.js	18.20.3	必须使用此版本或更高，解决 M1 芯片兼容性问题
Strapi	4.23.1	官方长期支持版本
@strapi/plugin-documentation	4.23.1	与 Strapi 核心版本严格匹配
npm	≥8.19.4	推荐 v10+

# 验证环境
node -v  # v18.20.3
npm -v   # 10.x.x

安装文档插件：正确姿势

推荐安装方式

npm run strapi install documentation

为什么推荐此方式？

• 自动匹配 Strapi 核心版本
• 自动生成默认配置
• 避免手动安装的版本冲突

验证安装

检查 package.json 确保版本一致：

"dependencies": {
  "@strapi/plugin-documentation": "4.23.1"
}

配置详解：定制你的文档

默认配置位置

./config/plugins.js (如不存在会自动使用内置默认配置)

完整配置示例

// config/plugins.js
module.exports = ({ env }) => ({
  documentation: {
    enabled: true,
    config: {
      openapi: "3.0.0",
      info: {
        version: "1.0.0",
        title: "管理系统 API",
        description: "项目专用接口文档",
        contact: {
          name: "技术支持",
          email: "support@test.cn"
        }
      },
      servers: [
        { 
          url: env("DEV_API_URL", "http://localhost:1337/api"), 
          description: "开发环境" 
        },
        { 
          url: env("PROD_API_URL", "https://api.test.cn"), 
          description: "生产环境" 
        }
      ],
      security: [{ bearerAuth: [] }],
      components: {
        securitySchemes: {
          bearerAuth: {
            type: "http",
            scheme: "bearer",
            bearerFormat: "JWT"
          }
        }
      },
      tags: [
        { name: "用户管理", description: "学生和教职工账户管理" },
        { name: "内容管理", description: "新闻、公告和学术内容" },
        { name: "系统管理", description: "权限和配置管理" }
      ],
      "x-strapi-config": {
        path: "/documentation",
        showGeneratedFiles: false, // 生产环境建议关闭
        generateDefaultResponse: true
      }
    }
  }
});

权限配置：保护你的文档

在 Strapi 管理后台设置访问权限：

1. 访问 http://localhost:1337/admin
2. 进入 设置 → 用户权限 → 角色
3. 为不同角色配置权限：
   • Public: 是否允许未认证用户访问
   • Authenticated: 认证用户权限
   • Administrator: 管理员权限

访问与使用文档

访问方式

• 开发环境 : http://localhost:1337/documentation
• Swagger UI 界面 :

关键功能

1. 接口测试：直接在文档中调用 API
2. 模型查看：查看请求/响应数据结构
3. 认证测试：右上角添加 Bearer Token
4. 分组查看：按标签筛选相关 API

文档更新机制

文档会在以下情况自动更新：

• Strapi 启动时
• 内容类型结构变更后
• 手动触发：设置 → 文档 → 生成新版本

生产环境最佳实践

安全配置建议

// config/env/production/plugins.js
module.exports = {
  documentation: {
    config: {
      "x-strapi-config": {
        showGeneratedFiles: false // 隐藏文件路径
      },
      servers: [{ 
        url: "https://api.prod.cn", 
        description: "生产环境" 
      }]
    }
  }
}

性能优化

1. 禁用开发功能：

   showGeneratedFiles: false,
   generateDefaultResponse: false

2. 启用缓存：

   cache: {
     enabled: true,
     maxAge: 3600000 // 1小时缓存
   }

常见问题解决

1. 安装时报错 Cannot find module 'ajv/dist/core'

解决方案：

# 清理缓存并重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install ajv@8.12.0 --save-exact
npm install

2. M1 芯片兼容性问题

必须使用 Node.js ≥18.20.3：

nvm install 18.20.3 --arch=arm64

3. 文档不更新

强制刷新方法：

1. 删除 .tmp/documentation 文件夹
2. 重启 Strapi
3. 在管理后台手动生成新版本

结语：文档即生产力

通过 Strapi 的文档插件，我们实现了：

• ✅ 零配置快速启动
• ✅ 自动生成精准的 OpenAPI 规范
• ✅ 交互式 API 测试环境
• ✅ 团队友好的文档协作

最佳实践组合：

• Node.js 18.20.3（解决 M1 兼容性问题）
• Strapi 4.23.1（稳定版本）
• 文档插件 4.23.1（严格版本匹配）

"好的文档不是项目的附属品，而是开发过程的核心组成部分。" ------ API 设计箴言

通过本文指南，你现在应该能够为清华管理系统搭建专业的 API 文档门户。立即访问你的 http://localhost:1337/documentation 体验吧！