在老大的指引下,需要将系统的 json 文件格式转换成 apidoc 的 json 格式,也就是 json 格式的重组,但是这个 apidoc 的生成格式是不固定的,因为 apidoc 有自己一套的生成规则,我需要研究一下是怎么生成的.
一,官方基础栗子二,理解 apidoc 生成静态文档的结构解读三,深入理解一下 apidoc 生成原理以及规则一,apidoc 基础栗子
全局安装 apidoc
npm install apidoc - g
1,首先建立文件目录2,需要你在 input 文件夹里面写上你的 js 部分
这个是栗子的 js 部分.
3,新建 apidoc.json 文件
/**
@api {get} /user/:id Request User information
@apiName GetUser
@apiGroup User
@apiParam {Number} id Users unique ID.
@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname Lastname of the User.
*/
/**
@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"
* }
*/
apidoc.json 栗子
4,在 myapp 文件夹下面运行
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url": "https://api.github.com/v1"
}
apidoc - i myapp / -o apidoc / -t mytemplate /
-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 是必须的,
@api {method} path [title]
比如
method 包括请求的方式:get,post,put,delete,等
path 表示请求的路径.
title (可选项)表示分组的解释,导航.
对应的静态页面
(2)@apiDefine
@apiDefine name[title][description]
表示的是:嵌入在 api 块或 api 中的文档块
没有找到对应的页面
标志位 api 方法的反对(不对)的地方.
(3)@apiDeprecated
@apiDeprecated[text]
(4)@apiDescription
表示的是描述.
@apiDescription text
页面上显示的是:
(5)@apiError 和 @apiErrorExample
表示的错误返回的参数
@apiError [(group)] [{type}] field [description]
页面的显示:
(6)@apiGroup
这个是必填项,表示的分组.
页面显示的是:
(7)@apiHeader
表示的是:传递给 API 头部的参数
@apiHeader [(group)] {type} [field=defaultValue] [description]
发现:@apiHeader 与 @apiParam 用法显示上很像,但是在生成的 api_data.json 所在的树形结构不一致.
,上面的红框是 @apiHeader 生成的,下面的红框是 @apiParam 生成的.
(8)@apiParam
表示的:传递给 API 方法的参数
页面显示的是:
(9)@apiParamExample
表示的是:参数实例
页面上的显示:
(10)@apiSuccess 和 @apiSuccessExample
表示的是:成功返回的参数.
页面上的显示:
目前主要用到了这 10 多个参数,还是够完成老大要求的任务.
saucxs 阅读 (
posted @
2018-01-11 17:36
...
) 评论 (
...
) 编辑 收藏
刷新评论 刷新页面 返回顶部
来源: https://www.cnblogs.com/chengxs/p/8249960.html