如何为MedusaJS v1.3.17自定义端点自动生成API参考？

MedusaJS基于Express构建，可借助Express生态的API文档工具自动生成自定义端点的参考文档，以下是几种实用方案：

方案1：Swagger/OpenAPI（最常用） #

通过swagger-jsdoc解析路由中的JSDoc注释，配合swagger-ui-express生成可视化API文档页面。

操作步骤： #

1. 安装依赖

npm install swagger-jsdoc swagger-ui-express --save-dev

2. 创建Swagger配置文件
   在项目根目录新建swagger.config.js，示例内容：

const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Medusa Custom API',
      version: '1.0.0',
      description: '自定义端点的API参考文档',
    },
    servers: [
      {
        url: 'http://localhost:9000', // 你的Medusa服务地址
      },
    ],
  },
  apis: ['./src/api/routes/**/*.js'], // 指定自定义端点的路由文件路径
};

const specs = swaggerJsdoc(options);
module.exports = specs;

3. 挂载Swagger UI到Medusa服务器
   修改src/api/index.js（无则创建），添加Swagger中间件：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const specs = require('../swagger.config');

module.exports = (rootDirectory, options) => {
  const app = express();
  
  // 挂载Swagger UI
  app.use('/docs', swaggerUi.serve, swaggerUi.setup(specs));
  
  return app;
};

4. 给自定义端点添加JSDoc注释
   在自定义路由文件中，为每个端点添加Swagger规范的注释，示例：

/**
 * @swagger
 * /store/custom-endpoint:
 *   get:
 *     summary: 获取自定义数据
 *     description: 返回特定业务场景的自定义数据
 *     responses:
 *       200:
 *         description: 成功获取数据
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: string
 *                   example: "自定义数据内容"
 */
router.get('/store/custom-endpoint', async (req, res) => {
  // 端点逻辑
  res.json({ data: '自定义数据内容' });
});

启动Medusa服务后，访问http://localhost:9000/docs即可查看可视化API文档。

方案2：基于TypeScript类型生成OpenAPI文档 #

如果项目使用TypeScript，可借助ts-openapi这类工具，通过TypeScript接口定义自动生成OpenAPI规范，无需手动编写JSDoc注释：

• 定义请求/响应的TypeScript接口
• 使用工具将接口转换为OpenAPI Schema
• 结合swagger-ui-express展示文档

最佳实践 #

• 修改自定义端点时，同步更新注释或TypeScript类型，确保文档与代码一致
• 生产环境可为文档路径添加身份验证，避免未授权访问
• 可将生成的OpenAPI规范导出为JSON，导入到Postman、Insomnia等工具中，方便团队测试

内容的提问来源于stack exchange，提问作者moboldi