ibase2.0规范文档-01：OpenAPI在eclipse的

2018-11-24 本文已影响0人 LucasLight

前后端分离的契约（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】=..&amp;【参数2等】=.. 【描术名】(【方法名】)&#13;
     * @apiGroup 【所属分类】&#13;
     * @apiName 【方法名】&#13;
     * @apiVersion 2.0.0&#13;
     * @apiDescription 【具体说明】&#13;
     * @apiParam {【参数类型】} 【参数1】 【参数1的描述】&#13;
     * @apiParam {【参数类型】} 【参数2】 【参数1的描述】&#13;
     * @apiSuccess {【成功返回类型】} return 【返回值说明】，每个元素包含属性如下：&#13;
     * @apiSuccess {【返回值属性类型】} .【返回值属性名1】 【属性说明】&#13;
     * @apiSuccess {【返回值属性类型】} .【返回值属性名2】 【属性说明】&#13;
     * @apiSuccessExample {json} 调用示例 &#13;
     * GET /【完整调用地址】?【参数1】=【参数1示例值】&amp;【参数2等】=【参数2示例值】&#13;
     * ========&#13;
     * HTTP/1.1 200 OK&#13;
     * &#13;     * 【返回结果示例，下面以返回json_list_object进一步说明&#13;
     * [&#13;
     * {sysId:"1123-123213-12321",&#13;
     *  catalog:"系统配置",&#13;
     *  key:"系统标题",&#13;
     *  value:"统一办理系统"},&#13;
     * {...}&#13;
     * ]】&#13;
     * @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&#13;
     * 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} 接口调用示例&#13;
     * 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} 参数示例&#13;
     * 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} 调用示例 &#13;
     * GET url&#13;
     * ========&#13;
     * HTTP/1.1 200 OK&#13;  * &#13;
     * 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>