产品管锥--Zoomla!逐浪CMS官方博客

更好的管理接口开发-用ApiDocs这款node工具编写后台文档和移动接口说明文件

作者:Q葩小玉 发布时间:2020-12-01 来源:本站原创 点击数: 分享网址

Q葩小玉

博主:Q葩小玉
个人座右铭:你想过普通的生活 就会遇到普通的挫折 你想过上最好的生活 就一定会遇上最强的伤害 这世界很公平 你想要最好 就一定会给你最痛~

有朋友问逐浪官方的接口文档(如:http://code.z01.com/apidoc )写得漂亮有什么秘决,这里分享一个工具。

简介

在开发后台 需要api的编写 那么在提供给web端和移动客户端的开发者时需要给他们提供必要的api文档 那么今天就来介绍

一个文档编写工具 apidocjs 整个语法还是遵循markdown的语法

当然apidoc支持Grunt,主页 https://github.com/apidoc/grunt-apidoc

其实这样类似的工具还有很多 但目的只有一个就是提供给其他开发者更好的说明 所以说文档的编写和规范都是十分重要的

安装

在命令行全局安装

$ npm install apidoc -g

apidoc支持Grunt,主页https://github.com/apidoc/grunt-apidoc

在项目中可以使用npm install grunt-apidoc —save-dev安装

添加grunt.loadNpmTasks(‘grunt-apidoc’)到Gruntfile.js

添加grunt task 这里面包含了输出目录等信息

apidoc: {
      myapp: {
        src: "app/",
        dest: "apidoc/"
      }
}
module.exports = function(grunt) {
    grunt.config.set('clean', {
      apidoc: {
        myapp: {
          src: "app/",
          dest: "apidoc/"
        }
      }
    });
    grunt.loadNpmTasks('grunt-apidoc');
};

安装完毕之后可以查看一下命令

$ apidoc -h

下面会看到一些参数 这里简单介绍几个

参数 说明
-o 指定文档的输出目录
-i 输入文件夹 这里包含了
-t 指定输出文件的模板
-c 指定配置文件的文件目录

接下来就是配置文件appidoc.json的定义 实例如下

{
  "name" : "codespace",
  "version": "1.0.0",
  "title": "codespace",
  "description": test project"
}

当然配置文件的内容放入package.json也是可以的(相同的字段就和package.json一样 而不一样的就放在apidoc下)

比如正在终端执行

$ npm init

填写你的项目信息即可 最后别忘了加上apidoc这个配置项

{
  "name": "codespace",
  "version": "1.0.0",
  "description": "test for codespace",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "api"
  ],
  "author": "jellybean",
  "license": "MIT",
  "apidoc":{
    "title":"codespace"
  }
}

当然为了生成最后的文档文件 我们还需要生成我们的代码文件 当然在实际项目中可以新建一个文档的文件

我们在myapp文件目录下新建生成doc.php 具体内容如下(文档的语法格式在接下来会介绍)

/**
 * @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.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

来到myapp的上级目录(当然也可以在当前目录 看具体执行的命令)

$  apidoc -i myapp/ -o apidoc/

这样的话会在当前目录生成apidoc的文件目录 里面就包含了最后文档的样式和内容 这样的话我们可以将文档直接部署到服务器
在这里插入图片描述

对于文档的语法当然具体的还是看 官方文档 https://apidocjs.com/ 这里就先介绍几个

首先文档的代码块是以/***/开始和结束 这个从上面的事例就可以看出

@api

定义接口的形式和地址 包括具体的请求类型和参数等

@api {method} path [title]

@apiName

定义接口名

@apiGroup

定义接口所属组 因为接口可能会分类 比如书籍类接口和评论类接口

@apiDefine

定义一组接口返回实例 这和@apiUse对应起来用(你可以理解为在这声明了一个function)

然后再需要的地方再使用 如我们现在定义一组错误提示

/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

这样的话我们可能在某个接口部分会使用到差找不到用户这个错误返回时可以加上

@apiUse UserNotFoundError

@apiHeader

定义了接口请求的头部信息 如

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiParam

接口的请求参数 列举出接口的请求参数 类型 是否可选等(可选的话[]包含参数名) 如

@apiParam {Number} id Users unique ID.
@apiParam {String} [firstname] Firstname of the User.

@apiSuccess

接口成功返回的字段信息 包括接口类型 描述

@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.

@apiSuccessExample Success-Response:
接口请求成功返回的形式事例 如

HTTP/1.1 200 OK
      {
        "firstname": "John",
        "lastname": "Doe"
      }

@apiError

定义接口的错误信息 包含错误类型和描述

@apiErrorExample Error-Response:

定义接口错误返回实例 如

HTTP/1.1 404 Not Found
      {
        "error": "UserNotFound"
      }

写在最后

懂技术的朋友还可以写一段powershell语法进行批处理,非常方便,下面我们也分享出来了:

$来源文件 = 'E:\ZoomLaCMS\Pages\API\WXAPP.cshtml'
$接口文件存驻 = 'E:\ApiDocs文档生成\接口源\'
$接口文档输出 = 'E:\ApiDocs文档生成/apidoc/'

# 拷贝接口文件
Copy-Item $来源文件 $接口文件存驻
# 更改后缀为.cs
(dir $接口文件存驻 -Filter *.cshtml)|rename-item -newname { $_.name -replace '\.cshtml','.cs' } 
# 执行apidoc生成接口中文档
apidoc -i $接口文件存驻 -o $接口文档输出
# 切换到接口文件夹
cd $接口文档输出
# 执行http-server运行
hs -o



本文责任编辑:  加入会员收藏夹 点此参与评论>>

进一步意向对[更好的管理接口开发-用ApiDocs这款node工具编写后台文档和移动接口说明文件]这条信息感兴趣吗?您还可以点此联系我们以确定进一步意向。
当前网址:
复制本网址-发给QQ/微信上的朋友
上一篇文章:基于nodejs的http-server服务使用介绍和命令全收集 下一篇文章:

+什么是CMS

CMS(Content Management System)是网站内容管理系统简称, 互联网上每个网站(无论大小门户)其后台都由专业CMS系统支撑- Zoomla!逐浪CMS作为国内高端CMS与WEB应用典范,首创第3代CMS理念,专注底层核心技术研发,以云技术、创新精神构建行业新成就,提供从网站内核到电商、办公、移动一体化的开发体验!

7×24小时服务热线 021-50391046 技术支持:13177777714
©Copyright 2003- 逐浪软件z01.com版权所有 All rights reserved
经营许可证号:工商3601002021063 沪ICP备09077823号 沪公网安备31011502000316号
本网站基于®Zoomla!逐浪CMS内核开发

ISO9001国际认证企业 CSDN外包TOP资质 鉴赏MTV电广视告 7×24小时全天候贴心服务 社会征信网