SpringBoot非官方教程 | 第十二篇:springboot集成apidoc
转载请标明出处:
原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot-apidoc/
本文出自方志朋的博客
首先声明下,apidoc是基于注释来生成文档的,它不基于任何框架,而且支持大多数编程语言,为了springboot系列的完整性,所以标了个题。
一、apidoc简介
apidoc通过在你代码的注释来生成api文档的。它对代码没有侵入性,只需要你写好相关的注释即可,并且它仅通过写简单的配置就可以生成高颜值的api接口页面。它基于node.js,所以你需要安装node.js环境。node.js安装,点击这里。这里就不介绍。
二、准备工作
安装完node.js安装api.doc,它的项目源码:https://github.com/apidoc/apidoc 。
通过命令安装:
npm install apidoc -g
三、注释怎么写
- @api
@api {method} path [title]
method:请求方法,
path:请求路径
title(可选):标题
- @apiDescription
@apiDescription text
text说明
- @apiError
@apiError [(group)] [{type}] field [description]
(group)(可选):参数将以这个名称分组,不设置的话,默认是Error 4xx
{type}(可选):返回值类型,例如:{Boolean}, {Number}, {String}, {Object}, {String[]}
field:返回值字段名称
descriptionoptional(可选):返回值字段说明
- @apiGroup
@apiGroup name
name:组名称,也是导航的标题
更多注释,参见官方文档:http://apidocjs.com/#params
四、写给栗子
首先写配置文件
在项目的主目录新建一个apidoc.json文件:
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
更多配置参考:http://apidocjs.com/#configuration
写个注释:
/**
* @api {POST} /register 注册用户
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用于注册用户
* @apiParam {String} account 用户账户名
* @apiParam {String} password 密码
* @apiParam {String} mobile 手机号
* @apiParam {int} vip = 0 是否注册Vip身份 0 普通用户 1 Vip用户
* @apiParam {String} [recommend] 邀请码
* @apiParamExample {json} 请求样例:
* ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"注册成功"}
*/
用apidoc命令生成文档界面
先cd到工程的外层目录,并在外层目建个输出文档的目录,我建的是docapi。
输命令:
apidoc -i chapter4/ -o apidoc/
-i 输入目录 -o 输出目录
chapter4是我的工程名。
可以看到在apidoc目录生成了很多文件:
打开index.html,可以看到文档页面:
五、参考资料
扫码关注公众号有惊喜
(转载本站文章请注明作者和出处 方志朋的博客)
SpringBoot非官方教程 | 第十二篇:springboot集成apidoc的更多相关文章
- SpringBoot非官方教程 | 第二十二篇: 创建含有多module的springboot工程
转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springbot22-modules/ 本文出自方志朋的博客 这篇文 ...
- (转)SpringBoot非官方教程 | 第十二篇:springboot集成apidoc
首先声明下,apidoc是基于注释来生成文档的,它不基于任何框架,而且支持大多数编程语言,为了springboot系列的完整性,所以标了个题. 一.apidoc简介 apidoc通过在你代码的注释来生 ...
- (转) SpringBoot非官方教程 | 第二十四篇: springboot整合docker
这篇文篇介绍,怎么为 springboot程序构建一个Docker镜像.docker 是一个开源的应用容器引擎,基于 Go 语言 并遵从Apache2.0协议开源.Docker 可以让开发者打包他们的 ...
- SpringBoot非官方教程 | 第二十六篇: sprinboot整合elk,搭建实时日志平台
转载请标明出处: 原文首发于https://www.fangzhipeng.com/springboot/2017/07/11/sprinboot25-elk/ 本文出自方志朋的博客 这篇文章主要介绍 ...
- SpringBoot非官方教程 | 第二十四篇: springboot整合docker
转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot24-docker/ 本文出自方志朋的博客 这篇文 ...
- SpringBoot非官方教程 | 第二十五篇:2小时学会springboot
转载请标明出处: http://blog.csdn.net/forezp/article/details/61472783 本文出自方志朋的博客 一.什么是spring boot Takes an o ...
- SpringBoot非官方教程 | 第十九篇: 验证表单信息
转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot19/ 本文出自方志朋的博客 这篇文篇主要简述如何 ...
- SpringBoot非官方教程 | 第十八篇: 定时任务(Scheduling Tasks)
转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot18-scheduling/ 本文出自方志朋的博客 ...
- SpringBoot非官方教程 | 第十六篇:用restTemplate消费服务
转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot11-restTemplate/ 本文出自方志朋的 ...
随机推荐
- bzoj 4574: [Zjoi2016]线段树
Description 小Yuuka遇到了一个题目:有一个序列a_1,a_2,?,a_n,q次操作,每次把一个区间内的数改成区间内的最大值,问 最后每个数是多少.小Yuuka很快地就使用了线段树解决了 ...
- JS常用的设计模式(3)-——观察者模式
观察者模式( 又叫发布者-订阅者模式 )应该是最常用的模式之一. 在很多语言里都得到大量应用. 包括我们平时接触的dom事件. 也是js和dom之间实现的一种观察者模式. div.onclick = ...
- (五)html部分标签元素补充
html标签元素十分的多,一次性掌握全部,那是不可能的,在后续的学习中,会不断补充标签元素... 1.行元素和块元素 行标签元素即是标签元素根据内容大小进行自适应,而不是占据一整行. 如<spa ...
- 码农的好助手:版本管理工具git的使用
一.什么是github? GitHub 是一个面向开源及私有软件项目的托管平台,因为只支持 Git 作为唯一的版本库格式进行托管,故名 GitHub. GitHub 于 2008 年 4 月 10 日 ...
- 成长之路--Docker入门
简介 Docker是一种新兴的虚拟化技术,能够一定程度上的代替传统虚拟机. Docker版本 Docker 划分为CE 和EE.CE 即社区版(免费,支持周期三个月),EE 即企业版,强调安全,付费使 ...
- Node中使用mysql模块遇到的问题
Node的mysql模块,本人的感受就是不好用,各种报错,各种坑,有一个问题困扰了我很久,也不知道是不是我使用的方式不对,不过后来用easymysql模块解决了,我才深信这是一个坑. 问题描述: 假设 ...
- CRM——讲师与学生
一.课程记录和学习记录 1.初始化 course_record, study_record.2.学习记录3.录入成绩4.显示成绩 ajax 查询 柱状图展示成绩 highcharts 5.上传作业(o ...
- jQuery动态添加删除CSS样式
jQuery框架提供了两个CSS样式操作方法,一个是追加样式addClass,一个是移除样式removeClass,下面通过一个小例子讲解用法. jQuery动态追加移除CSS样式 <!DOCT ...
- Linux中怎么从root用户切换到普通用户
su是在用户间切换,可以是从普通用户切换到root用户, test@ubuntu:~$ su Password: root@ubuntu:/home/test# 也可以是从root用户切换到普通用户 ...
- PHP:数字转Excel列头
转自我的个人博客:阔野飞花 http://www.rexcao.net/archives/169 前段时间升级一个项目的Excel导出功能,这次的列数大概有60多条,在处理过程中发现一个问题,原先做好 ...