工具名称：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

文章目录