团队高效率协作开发的秘密武器-APIDOC

时间:2022-10-20 16:53:32

团队高效率协作开发的秘密武器

已更新:可以在内网服务器中搭建一个yapi,感觉更好用

1.前言

在团队协作开发中,不知道各位有没有遇到这样的问题:

l 新人接手了项目代码,因没有项目文档,只能靠追踪路由,寻读代码分析业务逻辑

l 前端同学写好了页面,苦等后端接口规则,来写交互请求,获取数据

l 测试同学写测试用例,因项目还没完成,而迟迟无法开工

如何愉快地解决以上问题呢?答案就是它——APIDOC。

2.APIDOC是什么

APIDOC是一款Web API文档生成工具,可以根据代码注释自动生成静态html网页文档,不仅支持项目版本号,还支持接口版本号,接口版本更新升级后,文档接口可以很方便地对比阅读。像这样的接口文档生成工具有很多,如Java语言有Javadoc、PHP语言有PHPDoc、Python语言有Pydoc等,为什么要选择用它呢,因为它跨语言,不管你是用js、ruby、java、php、python、c#…,只要按规则写好注释,前后端兄弟都能用。让我们一起来见证它的强大之处吧。

3.先看看使用效果

整体一览~

团队高效率协作开发的秘密武器-APIDOC

图1

接口变更啦,比对阅读一下,清晰明白~

团队高效率协作开发的秘密武器-APIDOC

图2

看看返回数据,测试一发,可以开始写测试用例啦~

团队高效率协作开发的秘密武器-APIDOC

图3

4.具体实现流程

0x01 安装

Windows环境下安装方法:

  1. 官网nodejs.org下载nodejs
  2. 安装好后将npm 替换为淘宝镜像cnpm
npm install -g cnpm --registry=https://registry.npm.taobao.org

3.使用cnpm安装apidoc

cnpm install apidoc -g

0x02 用法

apidoc -i myproj/ -o mydoc/ [-c ./] -f ".*.js$"

-i 表示输入,myproj是项目文件夹路径

-o 表示输出,mydoc是要生成的接口文档路径

默认会带上-c,在当前路径下寻找配置文件(apidoc.json)

-f 为文件过滤,后面是正则表达式,示例为只选js文件

与-f类似,还有一个 -e 的选项,表示要排除的文件/文件夹,也是使用正则表达式

0x03 配置

新建apidoc.json文件,可参照官方配置示例

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

 

我的配置如下:

{
"name": "APP项目接口",
"version": "0.0.1",
"description": "测试文档",
"title": "APP项目接口",
"url" : "http://www.api.com/v1",
"sampleUrl" : "http://www.api.com/v1",
"order": ["User","Article"], }

  

配置属性简单介绍

name:项目名称

version:项目版本

description:项目介绍

title:浏览器显示的标题内容

url:请求的前缀,例如https://api.github.com/v1

sampleUrl:如果设置了,则在api文档中出现一个测试用的from表单

order:用于配置输出接口组的顺序

0x04 操作

1.在含有apidoc.json的文件夹(例如myproj)下新建myapp文件夹和mydoc文件夹,在myapp文件夹下新建user.php(注意文件格式要保存为utf-8,否则生成的API文档带中文的注释会产生乱码),我的user.php部分代码如下:

<?php

class User

{

/**

* @api {POST} /register 注册用户
* @apiGroup User
* @apiVersion 0.0.2
* @apiDescription 用于注册用户
* @apiParam {String} account 用户账户名
* @apiParam {String} password 密码
* @apiParam {String} mobile 手机号
* @apiParam {int} company = 0 是否注册企业用户 0 普通用户 1 企业用户
* @apiParam {String} [recommend] 邀请码
* @apiSampleRequest http://www.api.com/server.php
* @apiParamExample {json} 请求样例:
* ?account=test&password=11223344&mobile=182xxxx2345&company=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"注册成功"} */ public function register () { # code... } /** * @api {POST} /login 用户登录
* @apiGroup User
* @apiVersion 0.0.1
* @apiDescription 用于用户登录
* @apiParam {String} userName 用户名
* @apiParam {String} password 密码
* @apiParamExample {json} 请求样例:
* ?userName=张三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
* @apiSuccess (200) {String} user 用户信息
* @apiSuccess (200) {String} userId 用户id
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"登录成 功","userId":"1"} */ public function login() { # code... } }

  

2.回到myproj文件夹下,按住shift键并点击鼠标右键选择“在此处打开命令窗口”,在cmd命令窗口中执行如下命令:

apidoc -i myapp/ -o mydoc/

3.打开mydoc文件夹可以看到生成了含有index.html的网页文档,用浏览器打开index.html文件即可浏览文档效果图。

5.遇到的问题

问题一:

在浏览器打开静态文档下,选择相关接口,发送请求,收不到返回的json数据,打开浏览器F12中选择console可以看到,存在跨域问题。

解决办法:

将生成的api文档mydoc文件夹放在访问接口的同域名下(如使用效果图图3),通过域名访问该index.html文件。

问题二:

使用效果图中的接口组名(@apiGroup参数对应值)-“User”和“Article”换成中文后,在浏览器中打开显示为乱码。

解决办法:

主要是 @apiGroup 不支持utf-8 字符串,仅支持ascii码。官方有个办法可以实现utf-8字符串放置在@apiGoup 中。 代码如下:

/**
* @apiDefine User 用户接口
*/ /**
* @api {POST} /login 用户登录
* @apiGroup User
*/

解决效果

团队高效率协作开发的秘密武器-APIDOC

图4

6.总结

以上只是抛砖引玉,apidoc还有更多的用法,具体的介绍可以去官网查看,快来动手练练吧,掌握这款工具,带领团队吃鸡,无往而不利 。

团队高效率协作开发的秘密武器-APIDOC的更多相关文章

  1. 利用Team&commat;OSC进行团队协作开发平台

    利用Team@OSC进行团队协作开发平台 Team@OSC介绍 Team@OSC 是一个团队协作开发平台,轻松管理轻量级团队.代码运行平台(PaaS).代码质量检查应有尽有. 链接:https://t ...

  2. git的团队协作开发

    title: git的团队协作开发 date: 2018-04-24 14:00:03 tags: [git] --- 项目负责人创建组织架构 在控制面板中点击组织按钮,添加组织,在这里可以把组织理解 ...

  3. 图文详解如何利用Git&plus;Github进行团队协作开发

    团队协作开发中,大部分都会用到版本控制软件,比如Git.Svn等.本文将通过一个实例,详细讲解在真实的工作环境中,一个团队应该如何利用Git+Github进行协作开发,即详解Git工作流程.并就其中比 ...

  4. 零基础ASP&period;NET Core WebAPI团队协作开发

    零基础ASP.NET Core WebAPI团队协作开发 相信大家对“前后端分离”和“微服务”这两个词应该是耳熟能详了.网上也有很多介绍这方面的文章,写的都很好.我这里提这个是因为接下来我要分享的内容 ...

  5. Postman团队协作开发

    介绍 Postman是一款强大的API开发调试软件,它跨平台(真正跨平台,支持linux/mac os/windows),同时还提供浏览器插件,可以说是一个良心软件, 今天主要说一下Postman团队 ...

  6. TypeScript&colon; Angular 2 的秘密武器(译)

    本文整理自Dan Wahlin在ng-conf上的talk.原视频地址: https://www.youtube.com/watch?v=e3djIqAGqZo 开场白 开场白主要分为三部分: 感谢了 ...

  7. 第一章-第七题( 有人认为,&OpenCurlyDoubleQuote;中文编程”, 是解决中国程序员编程效率一个秘密武器,请问它是一个 &OpenCurlyDoubleQuote;银弹” 么&quest; )--By 侯伟婷

    首先,“银弹”在百度百科中的解释是银色的子弹,我们更熟知的“银弹”一词,应该是在<人月神话>中提到的.银弹原本应该是指某种策略.技术或者技巧可以极大地提高程序员的生产力[1].此题目中关于 ...

  8. Unity3D多人协作开发环境搭建

    多人协作 说到多人协作开发,大家都会想到要使用版本控制工具来管理项目,当然最常用的要数SVN和Git了,但是SVN管理Unity3D项目的确有一些不尽人意的地方. 比如:两个人修改了同一个场景,SVN ...

  9. C&num;秘密武器之扩展方法

    原文:C#秘密武器之扩展方法 为何要用扩展方法? 作为一个.NET程序猿,我们经常要跟.net自带类库或者第三方dll类库打交道,有时候我们未必能够通过反编译来查看它们的代码,但是我们通常需要给它们扩 ...

随机推荐

  1. 地址标记,SpringMVC转发与调用相关知识存档

    1.mytest_mavenprj1中,index的 <a href="login/login.html">点击登录</a> 与 <a href=&q ...

  2. Cocoa深入学习&colon;NSOperationQueue、NSRunLoop和线程安全

    http://blog.cnbluebox.com/blog/2014/07/01/cocoashen-ru-xue-xi-nsoperationqueuehe-nsoperationyuan-li- ...

  3. Json&period;Net系列教程 2&period;Net类型与JSON的映射关系

    原文 Json.Net系列教程 2.Net类型与JSON的映射关系 首先谢谢大家的支持和关注.本章主要介绍.Net类型与JSON是如何映射的.我们知道JSON中类型基本上有三种:值类型,数组和对象.而 ...

  4. Verify&lowbar;Execute 验证SQL语句执行结果

    #region Verify_Execute /// <summary> /// 验证insert.update.delete执行 /// </summary> /// &lt ...

  5. threejs 世界坐标转化为屏幕坐标

    网站: http://www.yanhuangxueyuan.com/Three.js_course/screen.html 方法.project 通过Vector3对象的方法project,方法的参 ...

  6. USACO Section 2&period;1 Sorting a Three-Valued Sequence 解题报告

    题目 题目描述 给N个整数,每个整数只能是1,2,或3.现在需要对这个整数序列进行从小到大排序,问最少需要进行几次交换.N(1 <= N <= 1000) 样例输入 9 2 2 1 3 3 ...

  7. vue案例 - v-model实现自定义样式の多选与单选

    接,上文:https://www.cnblogs.com/padding1015/p/9265985.html 这两天在玩mpvue,但是下午如果对着文档大眼瞪小眼的话,肯定会睡着的. 想起昨晚的fl ...

  8. Go语言Web框架gwk介绍 &lpar;五&rpar;

    Session Go的net/http本身不带session的机制,需要开发人员自行实现,gwk实现了内存中的session存储机制,如果需要将session存在其他地方比如redis或者memcac ...

  9. SenchaTouch 的一些问题记录

    1 : textfield 的 focus事件在手机上会被触发很多次,原因不明,在pc上测试无问题

  10. c语言printf&lpar;&rpar;输出格式大全&lpar;转载&rpar;

    1.转换说明符      %a(%A)     浮点数.十六进制数字和p-(P-)记数法(C99)      %c             字符      %d             有符号十进制整 ...