工具名称:apiDoc

Git地址:https://github.com/apidoc/apidoc
项目地址:http://apidocjs.com/
样例项目:http://apidocjs.com/example_basic/
apoDoc是从源码的注释中生成RestFul api 文档,样子还是蛮漂亮的

支持的样式标记

支持的注释样式:
JavaDoc-Style
/**

  • This is a comment.
    */

CoffeeScript

This is a comment.

Elixir
@apidoc """
This is a comment.
"""

Erlang(%不是必须的)
%{
% This is a comment.
%}

Perl (Doxygen)

**

This is a comment.

*

Python
"""
This is a comment.
"""

Ruby
=begin
This is a comment.
=end

安装apiDoc

npm install apidoc -g //全局安装

使用方法

在命令行中输入

apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/

参数说明:

-f 文件过滤
使用正则表达式,表示哪些文件需要本转换,不设置的情况下,默认为.cs .dart .erl .go .java .js .php .py .rb .ts 后缀的文件。

-i 代码文件夹

-o 输出Api文档的路径

-t 使用模板文件的路径,可以自定义输出的模板

常用的命令格式如下:

apidoc -i myapp/ -o apidoc/ 

配置

需要在代码文件夹的根目录下,创建apidoc.json文件
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}

配置属性如下:

name:项目名称
version:项目版本
description:项目介绍
title:浏览器显示的标题内容
url:endpoints的前缀,例如https://api.github.com/v1
sampleUrl:如果设置了,则在api文档中出现一个测试用的from表单
header
title:导航文字包含header.md文件
filename:markdown-file 文件名
footer
title:导航文字包含header.md文件
filename:markdown-file 文件名
order:用于配置输出 api-names/group-names 排序,在列表中的将按照列表中的顺序排序,不在列表中的名称将自动显示。

模板的配置:
在apidoc.json中或在package.json中添加template属性,将对模板进行特殊设置
forceLanguage:生成指定语言的文档,简体中文仅需设置"zh-cn",支持的语言:

https://github.com/apidoc/apidoc/tree/master/template/locales
0.19.1版本的apidoc中forceLanage得设置为zh_cn 而不是zh-cn 感谢评论区的蜗牛同学提醒

withCompare:是否启用与旧版本的比较功能,默认为true
withGenerator:是否输出生成信息,默认为true
jQueryAjaxSetup:设置Ajax请求的默认值,参见http://api.jquery.com/jquery.ajaxsetup/

简单使用示例

/**

  • @api {get} v1/api_userinfo 【获取】已注册用户信息接口
  • @apiDescription 获取已注册用户信息
  • @apiName api_userinfo
  • @apiGroup User
  • @apiParam {string} None
  • @apiParam {string} None
  • @apiSuccess {json} result
  • @apiSuccessExample {json} Success-Response:
  • {
  • "success" : "200",
  • "message":"success",
  • "result" : {
  • "user_login" : "loginName",
  • "user_email" : "loginEmail",
  • "user_registered" : "loginPass"
  • }
  • }
  • @apiSampleRequest http://localhost:8077/v1/api_userinfo
  • @apiVersion 1.0.0
    */

router.get('/v1/api_userinfo', function (req, res, next) {

var params = url.parse(req.url, true).query;

详细模版参数说明 移步:https://blog.csdn.net/soslinken/article/details/50468896

文章目录