如何用脚本自动生成API文档？

本文目录导读：

1. 基于代码注释的文档生成
2. OpenAPI/Swagger 自动生成
3. Postman 集合自动生成
4. 自动化脚本模板
5. 推荐工作流

我来介绍几种自动生成API文档的脚本方法：

基于代码注释的文档生成

JSDoc (JavaScript/TypeScript)

// 安装
npm install -g jsdoc
// 创建配置文件 jsdoc.json
{
  "source": {
    "include": ["src"],
    "includePattern": ".js$"
  },
  "opts": {
    "destination": "./docs",
    "template": "default"
  }
}
// 生成文档
jsdoc -c jsdoc.json
// 或一键命令
npx jsdoc src/*.js -d docs

Sphinx (Python)

# 安装
pip install sphinx sphinx-autodoc
# 初始化
sphinx-quickstart docs
# 配置 conf.py
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
# 生成文档
sphinx-apidoc -o docs/ src/
make html -C docs/

OpenAPI/Swagger 自动生成

Express + swagger-autogen

npm install swagger-autogen

swagger.js:

const swaggerAutogen = require('swagger-autogen')();
const doc = {
  info: { 'My API',
    description: 'Description'
  },
  host: 'localhost:3000',
  schemes: ['http']
};
const outputFile = './swagger-output.json';
const endpointsFiles = ['./routes/*.js'];
swaggerAutogen(outputFile, endpointsFiles, doc);
// 运行生成
node swagger.js

Spring Boot (Java)

// 在pom.xml添加依赖
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
// 配置类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }
}
// Maven命令生成文档
mvn springfox:generate

Postman 集合自动生成

使用 Newman

# 安装
npm install -g newman postman-collection-generator
# 生成Postman集合
newman run collection.json --reporters cli,htmlextra
# 或使用脚本
node generate-postman.js

generate-postman.js:

const fs = require('fs');
const endpoints = require('./apis.json');
const collection = {
  info: {
    name: "My API Collection",
    schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  item: endpoints.map(endpoint => ({
    name: endpoint.name,
    request: {
      method: endpoint.method,
      url: {
        raw: `{{base_url}}${endpoint.path}`,
        host: ["{{base_url}}"],
        path: endpoint.path.replace(/^\//, '').split('/')
      },
      header: endpoint.headers || [],
      body: {
        mode: 'raw',
        raw: JSON.stringify(endpoint.requestBody)
      }
    }
  }))
};
fs.writeFileSync('postman_collection.json', JSON.stringify(collection, null, 2));

自动化脚本模板

Bash脚本（多工具组合）

#!/bin/bash
echo "=== API文档生成器 ==="
# 1. 清理旧的文档
rm -rf docs/*
# 2. 从代码生成OpenAPI规范
echo "生成OpenAPI规范..."
npx swagger-autogen -o ./docs/openapi.json
# 3. 转换为Markdown文档
echo "生成Markdown文档..."
npx redoc-cli bundle docs/openapi.json -o docs/api-docs.html
# 4. 使用JSDoc生成内部文档
echo "生成JSDoc文档..."
npx jsdoc src/*.js -d docs/jsdoc
# 5. 生成Postman集合
echo "生成Postman集合..."
node scripts/generate-postman.js
echo "文档生成完成！"

触发器脚本（监听文件变化）

const chokidar = require('chokidar');
const { exec } = require('child_process');
// 监听API路由文件变化
const watcher = chokidar.watch('./src/routes/*.js', {
  ignored: /(^|[\/\\])\../,
  persistent: true
});
watcher.on('change', (path) => {
  console.log(`文件 ${path} 已更改，重新生成文档...`);
  exec('npm run generate-docs', (error, stdout, stderr) => {
    if (error) {
      console.error(`错误: ${error}`);
      return;
    }
    console.log(stdout);
  });
});
console.log('监听文档更新...');

推荐工作流

package.json 配置

{
  "scripts": {
    "docs:generate": "node scripts/generate-all-docs.js",
    "docs:watch": "node scripts/watch-docs.js",
    "docs:serve": "npx serve docs",
    "docs:publish": "npm run docs:generate && gh-pages -d docs"
  }
}

这样你就可以用一条命令生成完整的API文档了！