在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下!
该工具是Nodejs的模块,请务必在使用前安装好nodejs环境!
工具名称:apiDoc
Git地址:https://github.com/apidoc/apidoc
项目地址:http://apidocjs.com/
样例项目:http://apidocjs.com/example_basic/
apoDoc是从源码的注释中生成RestFul api 文档,样子还是蛮漂亮的……
自己写了的ApiDoc文档自动生成工具,避免每次写完后手动执行生成代码
http://blog.csdn.net/soslinken/article/details/50476384
支持的注释样式:
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
使用npm命令安装apidoc即可!
使用方式:
在命令行中输入
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/
配置
无package.json文件时,需要在代码文件夹的根目录下,创建apidoc.json文件。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
在该文件中即可配置apidoc
有package.json文件时,在package.json文件中添加"apidoc": { }属性即可。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"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/
我使用的配置如下:
{
"name": "测试",
"version": "0.0.1",
"description": "API文档测试",
"title": "API文档测试",
"url" : "http://xxxxxxx",
"sampleUrl" : "http://xxxxxxxx",
"template":{
"forceLanguage":"zh-cn"
}
}
先来个demo试试:
在myapp文件夹下创建e