自动生成API文档-apidoc

前言

对于一个后台开发者编写接口文档是必不可少的一件事,但是手动编写又很麻烦,网上出现了很多自动化生成的API文档框架,本篇文章就来介绍一下apidoc的在node开发过程中的基本使用。

用法

  • npm安装

对于我们在webstorm或者VScode创建的node后台项目,想要使用一个第三方的库,基本都需要npm安装一下,首先查看一下apidoc的官网(官网地址:http://apidocjs.com/#param-api-private

全局安装(也可以安装在dev环境)

  npm i apidoc -g   #全局安装
  • 环境配置apidoc

两种配置方式:

(1)在根目录中添加apidoc.json文件

{
"name": "example",
"version": "0.1.0", 
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1" 
}

(2)项目package.json配置api-doc

 "apidoc": {
    "title": "叔接口文档",
    "url": "http://localhost:6789"//该代码对应的域名或主机地址
  }
  • apidoc文件目录创建

    在根目录的public中创建apidoc文件夹

  • 对应路由地址(router)编写接口内容

    node后台项目,在开发过程中都会有一个router路由目录,里面用于存放前端请求的路由地址,每个接口卢有地址上方编写接口文档即可。

    post请求的一个规范:

/**
 * @api {post请求方式} /vip/manager/dropPrivilege 下架删除会员特权
 * @apiName /vip/manager/dropPrivilege
 * @apiGroup vip
 *
 * @apiParam {id} id 会员特权id
 *
 * @apiSuccessExample 请求成功:
 *
 * { code: 0, message: '特权删除成功' }
 *
 * @apiErrorExample 请求失败:
 *
 * { code: -1, message: '无该项特权' }
 */

规范中只是最近本使用,具体的注解参数可以查看这个地址: ApiDoc官网注解说明链接 :http://apidocjs.com/#param-api
- 项目terminal执行命令行:

apidoc -i routes/ -o public/apidoc/

执行这个命令后出现

info: Done.

表示文档生成成功,这时候会在之前public中创建的apidoc文件中中看到一些代码,其中的index.html文件就是接口文档访问时候展示的内容

Laravel API Documentation Generator 是一个用于生成 API 文档的工具,它可以基于 Laravel 项目中的路由、控制器和注释来创建文档。自定义生成的 API 文档样式和布局主要可以通过编辑生成器使用的模板文件来实现。以下是自定义样式和布局的一些步骤和建议: 1. **获取模板文件**: 你可以通过克隆 laravel-apidoc-generator 的 GitHub 仓库来获取默认的模板文件。模板文件定义了文档的结构和样式,通常包括 HTML 和 Markdown 文件。 ```bash git clone https://github.com/mpociot/laravel-apidoc-generator.git ``` 2. **修改模板文件**: 在获取模板文件后,你可以根据需要对其进行编辑,比如调整 HTML 结构、CSS 样式或者添加自定义的 JavaScript 脚本。这些模板文件通常位于 `resources/views` 文件夹内。 3. **配置生成器**: 当你安装了 laravel-apidoc-generator 并配置了 API 的路由和注释后,你可以在 `php artisan apidoc:generate` 命令执行时使用 `--template_folder` 选项指定你的自定义模板文件夹路径。 ```bash php artisan apidoc:generate --template_folder={path/to/your/template} ``` 4. **添加自定义样式和脚本**: 在模板文件中,你可以添加自定义的 CSS 链接或者 JavaScript 引用来进一步定制文档的外观和行为。确保这些资源在生成的文档中能够正确加载。 5. **更新依赖**: 如果你修改了模板并添加了新的资源文件,确保这些更改被正确处理,并且在生成文档时不会出现资源未找到的错误。 6. **测试你的更改**: 在自定义了样式和布局之后,运行生成命令并检查文档以确保所有更改都按预期工作。如果有任何问题,需要返回编辑模板文件进行调试。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值