apidoc 监视文件变动自动生成工具

迦蓝叶

已于 2024-12-09 11:39:40 修改

阅读量8.4k

点赞数 2

分类专栏： nodejs 开源工具推荐文章标签： apidoc nodejs 监测文件

于 2016-01-07 14:58:03 首次发布

本文链接：https://blog.csdn.net/soslinken/article/details/50476384

版权

开源工具推荐同时被 2 个专栏收录

8 篇文章

订阅专栏

nodejs

3 篇文章

订阅专栏

本文介绍了一款自定义工具，能够实时监控API文件变化并自动生成文档，提高开发效率。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

在开发过程中，文档的维护常常是一个繁琐且容易忽视的环节。尤其是对于Restful API的文档，每次更新代码后都需要手动重新生成文档，这无疑增加了开发者的工作负担。为了解决这个问题，我开发了一个能够自动监控文件变化并执行文档生成的工具，它基于apiDoc工具，但更加自动化和便捷。

工具介绍

这个工具的核心功能是自动监控api目录下的文件变化，并在检测到变化时自动执行文档生成命令。以下是具体的实现步骤和代码：

初始化和配置

首先，工具会检查api和doc目录是否存在，如果不存在，则创建这两个目录，并在api目录下生成apidoc.json配置文件。

var fs = require('fs');
var gaze = require('gaze');
var exec = require('child_process').exec;

function init() {
    fs.mkdirSync('./api');
    fs.mkdirSync('./doc');
    createConfigureFile();
    beginWatch();
}

function createConfigureFile() {
    var configure = {
        "name": "测试",
        "version": "0.0.1",
        "description": "API文档测试",
        "title": "API文档测试",
        "url": "http://xxxxxx",
        "sampleUrl": "http://xxx",
        "template": {
            "forceLanguage": "zh-cn"
        }
    };
    fs.writeFileSync('./api/apidoc.json', JSON.stringify(configure));
}

监控文件变化

接下来，工具使用gaze库来监控api目录下的文件变化，并在检测到变化时执行文档生成命令。

function beginWatch() {
    gaze('./api/*.*', function(error, watcher) {
        this.on('all', function(event, filepath) {
            console.log(filepath + ' was ' + event);
            runGeneration();
        });
    });
}

文档生成

当文件变化被检测到时，工具会执行apidoc命令来生成文档。

function runGeneration() {
    var com = exec('apidoc -i ./api -o ./doc');
    com.stdout.on('data', function(data) {
        console.log("生成Api->" + data);
    });

    com.stderr.on('data', function(data) {
        console.log('生成错误啦->' + data);
    });
}

启动

最后，工具会根据api和doc目录的存在情况来决定是直接开始监控还是先进行初始化。

if (fs.existsSync('./api') && fs.existsSync('./doc')) {
    beginWatch();
} else {
    init();
}

总结

这个工具极大地简化了API文档的维护工作，使得开发者可以更专注于代码的开发。通过自动监控文件变化并执行文档生成，它确保了文档的及时更新，减少了手动操作的需要。