apiDoc 一款很不错api文档生成工具
apiDoc 一款很不错api文档生成工具,在开发接口的时候,需要给同事看相应的接口文档。给大家推荐一个生成文档的工具--apiDoc,最后生成的文档以网页的形式发布,方便快捷,便于阅读。
创建项目目录
不多说。。。
1、安装模块
apidoc
依赖node.js
的包管理工具npm
进行安装,所以安装apidoc
之前要先安装node.js
(npm会在安装node时顺带进行安装)。
node 的安装教程可以参考→Node软件的安装流程
$ npm install apidoc -g # 或者
$ yarn add apidoc --global
2、配置package.json
"apidoc": {"title": "千锋HTML5学院","url" : "http://localhost:3000/"
}
3、简单使用示例
apidoc
是运用各个不同的注解来完成文档的写作的。学习apidoc
,主要就是学习注解的用法。
详情可看官网 https://apidocjs.com/
常用的关键字
@apiVersion verison接口版本,major.minor.patch的形式
@api {method} path [title]只有使用@api标注的注释块才会在解析之后生成文档,title会被解析为导航菜单(@apiGroup)下的小菜单method如{POST GET}
@apiGroup name分组名称,被解析为导航栏菜单
@apiName name接口名称,在同一个@apiGroup下,名称相同的@api通过@apiVersion区分,否者后面@api会覆盖前面定义的@api
@apiDescription text接口描述,支持html语法@apiIgnore [hint]apidoc会忽略使用@apiIgnore标注的接口,hint为描述
@apiSampleRequest url接口测试地址以供测试,发送请求时,@api method必须为POST/GET等其中一种@apiDefine name [title] [description]定义一个注释块(不包含@api),配合@apiUse使用可以引入注释块在@apiDefine内部不可以使用@apiUse
@apiUse name引入一个@apiDefine的注释块@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]用法基本类似,分别描述请求参数、头部,响应错误和成功group表示参数的分组,type表示类型(不能有空格),入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example用法完全一致,但是type表示的是example的语言类型example书写成什么样就会解析成什么样,所以最好是书写的时候注意格式化,(许多编辑器都有列模式,可以使用列模式快速对代码添加*号)@apiPermission namename必须独一无二,描述@api的访问权限,如admin/anyone
index.js
const express = require('express');
const cors = require('cors');
const app = express(); // 无需设置 utf-8的编码格式,默认就是app.use(cors());
app.use(express.urlencoded({ extended: false }));
app.use(express.json());// 设置静态目录
app.use('/apidoc', express.static('apidoc'));let users = [{ id: 5, name: '刘仪', gender: '男', old: 22 },{ id: 2, name: '张霞', gender: '女', old: 19 },{ id: 1, name: '赵翔', gender: '男', old: 21 }
];app.get('/', (req, res) => {console.log('home');res.send('<h1>首页</h1><p>建设中...</p>'); // 默认就是解析输出
});/*** @api {get} /users 1 获取用户列表* @apiGroup users*/
app.get('/users', (req, res) => {res.send(users);
});/*** @api {post} /users 2 新增用户* @apiGroup users** @apiParam {String} name='张三' 姓名* @apiParam {String} gender='男' 性别* @apiParam {Number} old=19 年龄*/
app.post('/users', (req, res) => {const len = users.length;let newId = len + 1;let ids = [];// 1 把id取出来users.forEach((user) => {ids.push(user.id);});// 2 升序排序ids.sort();// 3 判断是否有空缺for (let id = 1; id <= len; id++) {console.log(id);if (id !== ids[id - 1]) {newId = id;break;}}users.push({id: newId,name: req.body.name,gender: req.body.gender,old: req.body.old});res.send(users);
});/*** @api {put} /users/:id 3 修改用户* @apiGroup users** @apiParam {String} name='张三' 姓名* @apiParam {String} gender='男' 性别* @apiParam {Number} old=19 年龄*/
app.put('/users/:id', (req, res) => {const index = users.findIndex((user) => user.id == req.params.id);if (index != -1) {users.splice(index, 1, {id: req.params.id,name: req.body.name,gender: req.body.gender,old: req.body.old});}res.send(users);
});/*** @api {delete} /users/:id 4 删除用户* @apiGroup users*/
app.delete('/users/:id', (req, res) => {const index = users.findIndex((user) => user.id == req.params.id);if (index != -1) {users.splice(index, 1);}res.send(users);
});app.listen(3000, () => {console.log('your server is running at http://localhost:3000');
});
apiDoc 一款很不错api文档生成工具
4、编写完成后运行,生成在线接口文档
# -i 编译文件目录 -e 排除目录(不编译) -o 文档输出目录
$ apidoc -i ./ -e node_modules -o apidoc
5、访问接口文档
http://localhost:3000/apidoc
apiDoc 一款很不错api文档生成工具,更多免费资料领取
apiDoc 一款很不错api文档生成工具相关推荐
- 猿创征文|小而巧的API文档生成工具之smart-doc
文章目录 smart-doc介绍 smart-doc特性 smart-doc的最佳搭档 谁在使用smart-doc smart-doc的优缺点 smart-doc和swagger区别比较 smart- ...
- java smart算法_Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景 没有背景.就自己做自己 ...
- php自写api文档生成工具
框架改版后的第二个版本定下来了,这两天也比较轻松,于是就折腾给项目建个好看的api文档. 各种折腾.先是折腾phpDocumentor2,用phpdoc开源工具来建立文档,好不容易安装成功,各个模板都 ...
- springboot的api_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
- android api文档_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
- [aspnetcore.apidoc]一款很不错的api文档生成工具
简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api文档角度来说,从前后端文档沟通角度来 ...
- 一款零注解侵入的 API 文档生成工具,你用过吗?
以下文章来源方志朋的博客,回复"666"获面试宝典 介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart ...
- 推荐 6 款还不错的文档协作工具~
你们团队是否正在寻找便捷丰富功能的文档协作软件? 文件协作软件帮助你和你的团队更有效地工作,并进行实时协作,为创新创造更多的空间. 但是,今天有数百种文档协作工具,你应该选择哪一种呢? 为了帮助你,我 ...
- Api文档生成工具与Api文档的传播(pdf)
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
最新文章
- git命令从入门到实战,看这一篇足矣
- echo服务器(回显服务器)
- angular创建组件命令
- sql server charindex函数和patindex函数详解(转)
- LeetCode题解
- 反射学习系列2-特性(Attribute)
- java replace stringbuilder_Java StringBuilder replace()方法
- pxe安装linux dhcp失败,利用PXE自动化安装Centos时启动DHCP服务时遇到错误,请求大佬指教...
- OpenGL基础41:几何着色器
- 【干货】如何打造高质量的NLP数据集
- Spark API 之 cogroup 使用
- ...三个点es6用法
- java blazeds,java web开发学习-8 BlazeDS
- 【STM32F429的DSP教程】第8章 DSP定点数和浮点数(重要)
- win10 家庭版cmd命令打开超级管理员和关闭超级管理员
- 基于SpringBoot的库存管理系统
- Unity3D占用内存太大怎么解决呢? -尾
- Java版战棋(SLG)游戏AI及寻径处理入门
- xmind8使用甘特图与导出甘特图PDF
- 数据分析常用五大软件介绍