在老大的指引下,需要将系统的json文件格式转换成apidoc的json格式,也就是json格式的重组,但是这个apidoc的生成格式是不固定的,因为apidoc有自己一套的生成规则,我需要研究一下是怎么生成的。
一、官方基础栗子
二、理解apidoc生成静态文档的结构解读
三、深入理解一下apidoc生成原理以及规则
一、apidoc基础栗子
全局安装apidoc
1、首先建立文件目录
2、需要你在input文件夹里面写上你的js部分
这个是栗子的js部分。
@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname Lastname of the User.
<span style="color: #008000;">/<span style="color: #008000;">
@api {post} /user/:id Create User information
@apiName CreateUser
@apiGroup User
@apiParam {Number} id Users unique ID.
@apiSuccess {String} data
@apiSuccess {String} data.firstname Firstname of the User.
@apiSuccess {String} data.first.lastname Lastname of the User.
@apiSuccessExample {json} Success-Response:
-
HTTP/1.1 200 OK
- {
- "firstname": "John",* "lastname": "Doe"
- }
<span style="color: #008000;">*/
3、新建apidoc.json文件
apidoc.json栗子
4、在myapp文件夹下面运行
官网原文:Creates an apiDoc of all files within dir myapp/
,uses template from dir mytemplate/
and put all output to dir apidoc/
.
-i 是输入文件的路径 , -o 是输出文件的路径, -t是使用模板的路径(可缺省)
打开output文件夹,发现生成一个apidoc在线文档,直接打开html就可以看到
打开html文件
二、理解apidoc生成静态文档的结构解读
一个静态的文档很漂亮的生成了,但是实际控制这个现实的是api_data.js和api_project.js。但是实际上的数据显示是由api_data.json和api_project.json这两个json文件。
所以在支持将其他json格式转换成api_data.json和api_project.json,把apidoc生成的这两个文件进行替换,然后替换js文件,直接生产静态文档。
可以看一下api_data.json格式
对比一下api_data.js格式
很明显就能看出来,就是在api_data.json的基础上,封装成了一层,加上define({ "api": api_data.json});
api_project.json和api_project.js也是使用相同的方法封装的。
三、深入理解一下apidoc生成原理以及规则
apidoc设计到如下的参数
(1)第一个是@api
@api是必须的,
比如
method 包括请求的方式:get,post,put,delete,等
path 表示请求的路径。
title (可选项)表示分组的解释,导航。
对应的静态页面
(2)@apiDefine
表示的是:嵌入在api块或api中的文档块
没有找到对应的页面
(3)@apiDeprecated
标志位api方法的反对(不对)的地方。
(4)@apiDescription
表示的是描述。
页面上显示的是:
(5)@apiError和@apiErrorExample
表示的错误返回的参数
页面的显示:
(6)@apiGroup
这个是必填项,表示的分组。
页面显示的是:
(7)@apiHeader
表示的是:传递给API头部的参数
发现:@apiHeader与@apiParam用法显示上很像,但是在生成的api_data.json所在的树形结构不一致。
(8)@apiParam
表示的:传递给API方法的参数
页面显示的是:
(9)@apiParamExample
表示的是:参数实例
页面上的显示:
(10)@apiSuccess和@apiSuccessExample
表示的是:成功返回的参数。
页面上的显示:
目前主要用到了这10多个参数,还是够完成老大要求的任务。
apidoc的输入的js文件
<div class="cnblogs_code">
id of the User was not found. * * @apiErrorExample Response (example): * HTTP/1.1 401 Not Authenticated * { * "error": "NoAccessRight" * }<span style="color: #008000;">/
<span style="color: #008000;"><span style="color: #008000;">*/
- @api {post} /user Create a new User
- @apiVersion 0.3.0
- @apiName PostUser
- @apiGroup User
- @apiDescription In this case "apiUse" is defined and used.
- Define blocks with params that will be used in several functions,so you dont have to rewrite them.
- @apiParam {String} name Name of the User.
- @apiSuccess {String} id The new Users-ID.
- @apiUse CreateUserError
<span style="color: #008000;">/<span style="color: #008000;">
- @api {put} /user/:id Change a new User
- @apiVersion 0.3.0
- @apiName PutUser
- @apiGroup User
- @apiDescription This function has same errors like POST /user,but errors not defined again,they were included with "apiUse"
- @apiParam {String} name Name of the User.
- @apiUse CreateUserError
<span style="color: #008000;">*/