多语言方案
doxygen
apidoc
Swagger
api blueprint
重点在于“生成”,swagger和api blueprint选型时都考虑过,最终还是选择了apidocjs,
使用它扩展的javadoc annotation很方便,文档与代码一体化
如果从设计阶段开始,不嫌麻烦的话,可以采用RAML,mule提供了在线编辑器,
eclipse也有插件可以由JAX-RS的java代码生成。
单语言php方案
apigen
phpdocument2
yii2提供的apidoc方案。
http://www.yiiframework.com/doc-2.0/ext-apidoc-index.html
单语言js方案
jsapi
需要写APIDOC的应用场景:
1.api-business和api-middleware提供给client-*开发控制器逻辑。
2.javascript的一些组件封装库api
3.php的widget的一些组件封装库api
写word文档即可??
代码就是文档!!!
1.语言的升级、设计模式、组件化=》从机器理解的角度进行封装抽象。(自下而上设计)
2.以人可以理解的模型去抽象表达机器的表达模型并确保人能理解的表达模型具有一定的通用性,构造出人可以理解的模型后自动代码生成机器理解的模型自动化生成机器代码。(自上而下设计)
OA
SAP(业务抽象出一种新的表达语言并且具备可视化编程效果)
http://www.yaqi.net/
方案选型:
1.apidoc
只用于写api-bussiness的后台restful的api接口。其他的后台接口无需写接口文档。
http://apidocjs.com/
2.
@TODO
1.学习apidoc的参数定义以及写法模版,phpstorm中自动填写。
统一phpstorm使用的软件版本,phpstorm配置参数进行统一SVN管理并且进行合并增加最新的配置。
2.apidoc虚拟机中安装,以及整合到项目中自动生成对应的api-business的模块接口文件的,写自动化生成api接口的命令封装,将生成好的API文档整合到apache工程中可以本地访问。
3.发布虚拟机镜像,修改相关的API接口的接口案例,后台开发全员修改接口培训API接口文档的编写规范,前端学会使用最新的接口文档。
4.存在的问题优化。
APIDOC的错误信息描述模版如下,目前项目太小忽略版本号定义,后台接口全部统一POST方法。
制作phpstorm的live template识别关键词为api+tab
/**
* @api {post} controller/action action标题
* @apiName controller/action
* @apiGroup module
* @apiDescription action描述
* @apiParam {string} field1 描述1
* @apiParam {int} field2 描述2
* @apiParam {bool} field3 描述3
* @apiParam {decimal} field4 描述4
* @apiParam {jason} field5 描述5
* jason数据结构描述
* @apiSuccess (OK) {object} data 服务器返回的json数据
* jason数据结构描述
* @apiError (ERR) ERR_Module_UserDefinedErrorName1 错误描述1
* @apiError (ERR) ERR_Module_UserDefinedErrorName2 错误描述2
*/