express项目 apidoc 自动生成文档简洁教程

短命女 2023-02-22 03:54 71阅读 0赞

本文是关于apidoc的配置教程，具体的参数请参考[官方网站][Link 1]

## ##

### 全局安装apidoc ###

npm i apidoc -g

### 配置api-doc ###

方式1：根目录添加apidoc.json（推荐），apidoc.json内容如下，具体属性请参考

{
        "name": "user-service",
        "version": "1.0.0",
        "description": "用户服务API文档",
        "title": "user-service API Doc",
        "url": "http://localhost:8080/",
        "sampleUrl": "http://localhost:8080/",
        "forceLanguage": "zh-cn",
        "template": {
            "withCompare": true,
            "withGenerator": true
        }
    }

方式2：项目package.json配置api-doc

{
        "name": "test",
        "version": "0.0.0",
        "private": true,
        "scripts": {
            "start": "node ./bin/www"
        },
        "dependencies": {
            "cookie-parser": "~1.4.3",
            "debug": "~2.6.9",
            "ejs": "~2.5.7",
            "express": "~4.16.0",
            "http-errors": "~1.6.2",
            "morgan": "~1.9.0"
        },
        "devDependencies": {
            "express-session": "^1.15.6",
            "mysql": "^2.15.0"
        },
        "apidoc": {
            "name": "user-service",
            "version": "1.0.0",
            "description": "用户服务API文档",
            "title": "user-service API Doc",
            "url": "http://localhost:8080/",
            "sampleUrl": "http://localhost:8080/",
            "forceLanguage": "zh-cn",
            "template": {
                "withCompare": true,
                "withGenerator": true
            }
        }
    }

### 编写api文档 ###

以我的项目为例，我的api请求明细写在routes中，那么，我将api文档写在routes的文件中

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hSTTI0NTQ_size_16_color_FFFFFF_t_70][]

以查询用户数据的接口为例

### 设置静态文件目录 ###

一般这一步在创建项目的时候已经完成，但还是需要检查一下，假设我们需要将文档内容生成再public目录下，我们需要在app.js中配置

// 设置 public 文件夹为存放静态文件的目录
    app.use(express.static(path.join(__dirname, 'public')));

### 生成文档 ###

打开终端，cd到项目的根路径下，执行以下命令

apidoc -i routes/ -o public/apidoc/

其中，-i 是api目录； -o 是生成文档的目的地。生成完成后，项目根路径下会生成public/apidoc文件夹。

### 预览 ###

启动项目，在浏览器中输入   [http://localhost:3000/apidoc][http_localhost_3000_apidoc]

其中，3000 是项目启动的端口号，这里是不固定的，视情况而定。打开成功后，会出现这样的内容

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hSTTI0NTQ_size_16_color_FFFFFF_t_70 1][]

至此，文档生成成功。

[Link 1]: https://apidocjs.com/#demo
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hSTTI0NTQ_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200701143547792.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hSTTI0NTQ=,size_16,color_FFFFFF,t_70
[http_localhost_3000_apidoc]: https://links.jianshu.com/go?to=http%3A%2F%2Flocalhost%3A3000%2Fapidoc
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hSTTI0NTQ_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200701145327130.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hSTTI0NTQ=,size_16,color_FFFFFF,t_70