前言

实用过几款API的设计工具，有几款在线的版本，很好。可惜有的时候api是私有的，不能放在网上。offline版本的不是很多。以前使用过apidoc，写的文章也是放在evernote上了，现在重新回头写写，以免到时候使用的时候又忘记了。有些东西不经常使用，总会忘记。 这个的优点，可以定义不同版本的API，而且进行相同API在不同版本间的比较。

http://apidocjs.com http://apidocjs.com

安装

npm install apidoc -g

使用说明

  • 创建一个apidoc.json文件，可以保存api的一些简要说明，这个最后输出的时候会在首页显示。
{
  "name": "Demo APIs",
  "version": "2.0.0",
  "description": "这个是API协议的说明",
  "title": "Demo API",
  "template": {
  	"withCompare": true,
  	"withGenerator": true
  }
}
  • 命名 应该使用一致的命名规则，这将很容易进行理解。例如
@apiUse LoginParam, @apiUse LoginError, @apiUse LoginSuccess
  • 参数API
    -所有的参数
@api
@apiDefine
@apiDescription
@apiError
@apiErrorExample
@apiExample
@apiGroup
@apiHeader
@apiHeaderExample
@apiIgnore
@apiName
@apiParam
@apiParamExample
@apiPermission
@apiSampleRequest
@apiSuccess
@apiSuccessExample
@apiUse
@apiVersion
  • demo说明
/**
 * @apiDefine LoginParam
 * @apiParam {String} username Your e-mail-address.
 * @apiParam {String} password Your password.
 */

/**
 * @apiDefine UserParam
 * @apiParam {String} firstname Your firstname.
 * @apiParam {String} lastname  Your lastname.
 * @apiParam {Date}   birthday  Your birthday.
 */

/**
 * @api {GET} /account/register Register a new user.
 * @apiUse LoginParam
 * @apiUse UserParam
 * @apiParam {Boolean} terms Checkbox to accept the terms.
 */

/**
 * @api {GET} /account/login Signin with an existing user.
 * @apiUse LoginParam
 * @apiParam {Boolean} rememberme Checkbox to auto-login on revisit.
 */
  • 组。如果多个api可能相关。可以放在一组。这样输出展示就可以展现在一起。
/**
 * @apiDefine AccountGroup Account endpoints
 *
 * Here is the description for the "AccountGroup".
 * It can contain **markdown** syntax.
 */

/**
 * @api {GET} /account/login Signin with an existing user.
 * @apiGroup AccountGroup
 */
 
 

/**
 * @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.
 */

生成

  • example apidoc -i apis/ -o doc/ 将会把文件都生成到doc中。

支持的语言

  • C#, Go, Dart, Java, JavaScript, PHP, Scala (all DocStyle capable languages):
/**
 * This is a comment.
 */
  • Python
"""
This is a comment.
"""
  • Erlang:
%{
This is a comment.
%}

-其他Ruby Perl CoffeeScript等。

工具组件

  • Eclipse PDT apiDoc editor templates 地址 。例子图片图片

  • Eclipse Java apiDoc 地址 。例子图片图片

  • 还有我们最常用的Sublime Text的插件。apiDoc Autocompletion
    安装步骤，搜索apiDoc Autocompletion 进行安装，

最后说下我们输出的页面的展示了 看截图

screenshot