前后端分离的契约（http接口文档）
在做前后端分离开发时，后端开发的服务需要有帮助说明。
目前我们选用的是apidoc这个工具，其优点是，可以通过注释提取生成帮助文档。写代码加注释在一起就可以完成，不需要额外维护文档。
为了方便各位开发者在开发过程中对于接口有更明晰的查看和定位，
为了方便后端开发人员添加注释，创建代码模板（eclipse）如下：
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<templates>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc定义入口" enabled="true" name="@api">@api {POST|GET} uri title</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc添加常用注释模板，【】包含内容要替换" enabled="true" name="@apiAll">@api {GET【或POST】} ./【相对应用的调用地址】?【参数1】=..&【参数2等】=.. 【描术名】(【方法名】)
* @apiGroup 【所属分类】
* @apiName 【方法名】
* @apiVersion 2.0.0
* @apiDescription 【具体说明】
* @apiParam {【参数类型】} 【参数1】 【参数1的描述】
* @apiParam {【参数类型】} 【参数2】 【参数1的描述】
* @apiSuccess {【成功返回类型】} return 【返回值说明】，每个元素包含属性如下：
* @apiSuccess {【返回值属性类型】} .【返回值属性名1】 【属性说明】
* @apiSuccess {【返回值属性类型】} .【返回值属性名2】 【属性说明】
* @apiSuccessExample {json} 调用示例
* GET /【完整调用地址】?【参数1】=【参数1示例值】&【参数2等】=【参数2示例值】
* ========
* HTTP/1.1 200 OK
* * 【返回结果示例，下面以返回json_list_object进一步说明
* [
* {sysId:"1123-123213-12321",
* catalog:"系统配置",
* key:"系统标题",
* value:"统一办理系统"},
* {...}
* ]】
* @apiSampleRequest http://192.168.10.29:8080/【完整调用地址】</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc定义一个注释块" enabled="true" name="@apiDefine">@apiDefine name title
* desc</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc 接口描述，支持html语法" enabled="true" name="@apiDescription">@apiDescription text</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc接口举例" enabled="true" name="@apiExample">@apiExample {url} 接口调用示例
* example</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc 设置分组" enabled="true" name="@apiGroup">@apiGroup defname</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc 接口名" enabled="true" name="@apiName">@apiName name</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc一个参数描述" enabled="true" name="@apiParam">@apiParam {type} field=defaultValue description</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc参数示例" enabled="true" name="@apiExample">@apiExample {queryString} 参数示例
* example</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc 演示地址" enabled="true" name="@apiSampleRequest">@apiSampleRequest http://192.168.10.29:8080/server</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc返回值描述，如果有成员变量，field以点(.)开头" enabled="true" name="@apiSuccess">@apiSuccess {type} return description</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc调用示例" enabled="true" name="@apiSuccessExample">@apiSuccessExample {json} 调用示例
* GET url
* ========
* HTTP/1.1 200 OK *
* result</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc引入一个定义注释块" enabled="true" name="@apiUse">@apiUse name</template>
<template autoinsert="true" context="javadoc" deleted="false" description="Web API doc接口版本号" enabled="true" name="@apiVersion">@apiVersion 2.0.0</template>
</templates>
1. 导入模板
导入模板
2. 使用模板写api文档
- 在需要添加注释的Web方法前添加文档注释，即/**开头来利用模板自动补全出来块状注释。
- 在注释区域输入注解
@apiall即可有提示信息，按下回车添加注释模板（同时删除之前生成的无用的注解：@param/@return等）。
图示效果
输出openAPI文档
在需要提供文档给其他人时，按如下命令生成（需要安装apidoc，详细使用可参见源码目录下的webApi.bat）
apidoc -i 要生成文档的扫描目录 -o 输出目录 -f 要扫描的文件
生成效果
生成效果1
生成效果2
