告别手写 API文档生成工具推荐
发表于 10:19|
作者张红月
摘要：随着API的迅速发展，如何编写出更加规范的API文档说明则显的尤为重要。你是否还通过手写的方式来生成和编写这些文档呢？那么你就OUT啦！话说工欲善其事必先利其器，本文分享8款非常好的API文档生成工具给大家。
随着API的发展以及需求的日益增加，对API文本文档的需求与随之而来。相信许多开发人员都遇到过编写API文档方面的问题及烦恼。你是否还通过手写的方式来生成和编写这些文档呢？那么你就OUT啦！话说工欲善其事必先利其器，本文分享8款非常好的API文档生成工具给大家。
Web API文档工具列表
——Swagger框架可以通过代码生成漂亮的在线API，甚至可以提供运行示例。支持Scala、Java、Javascript、Ruby、PHP甚至 Actionscript 3。在线&。
——I/O Docs是一个用于RESTful Web APIs的交互式文档系统。使用 JSON 模型根据资源、方法和参数定义 APIs。I/O Docs 将生成 JavaScript 客户端接口，可通过这些接口来调用系统。服务器端基于&&开发。在线
——能够快速启动和运行文档，包括GitHub集成和I/O验证——更多建议可以前往Reddit查看上关于
——Docco是一个快速而随意、hundred-line-long、迭代程序风格的文档生成器。它会以HTML的方式显示评论和代码。
——非常灵活的一款文档工具，支持任何语言编写的API。
——Doxgen可以从一套归档源文件开始，生成HTML格式的在线类，或离线的LATEX、RTF参考手册。对于未归档的源文件，也可以通过配置Doxygen来提取代码结构。&更多建议可以前往Reddi上查看
相关讨论。
——是一款付费的文档API工具。里面包含了智能WIKI编辑器、基于标准的Markdown、文档分支、还可以与Git、SVN、Mercurial同步、整洁的主题、友好的界面。以上仅是作者在实践中发现的一些很好的工具，如果你有更好的建议或工具推荐，欢迎与我们分享。来自：
推荐阅读相关主题：
CSDN官方微信
扫描二维码,向CSDN吐槽
微信号：CSDNnews
相关热门文章10款流行的Markdown编辑器，总有一款适合你
发表于 11:16|
作者开源大叔
摘要：作为一个开源人，如果你不会使用Markdown语法，那你就OUT了！Markdown 是 2004 年由 John Gruberis 设计和开发的纯文本格式的语法，非常的简单实用。
作为一个开源人，如果你不会使用Markdown语法，那你就OUT了！Markdown 是 2004 年由 John Gruberis 设计和开发的纯文本格式的语法，非常的简单实用。
、项目README文件、文档项目甚至包括ISSUES和项目评论等都是支持Markdown语法的！
以下，我们收集了10个业界最受欢迎的Markdown编辑器，喜欢用Markdown的朋友都来看看吧！（以下排名仅为一家之言，请勿拍砖）
1.MarkdownPad
用户可以通过键盘快捷键和工具栏按钮来使用或者移除 Markdown 格式。MarkdownPad左右栏的分割方式令用户可以实时看到 HTML
格式的 Markdown 文档。
下载地址：
ReText 是一个使用 Markdown 语法和 reStructuredText (reST) 结构的文本编辑器，编辑的内容支持导出到
PDF、ODT 和 HTML 以及纯文本，支持即时预览、网页生成以及 HTML 语法高亮、全屏模式，可导出文件到 Google Docs 等。
下载地址：
WMD (wmd-editor)是一个简单轻量级的HTML编辑器，使用的是 Markdown 文本格式数据，适合用来做博客评论、发帖和一些基本的内容发布系统，支持流行的各种浏览器。
下载地址：
Mou 是 Mac下杰出的 Markdown 编辑器，提供语法高亮、在线预览、同步滚动、全屏模式，支持自定保存、自动匹配，允许自定义主题，支持
CSS，HTML 和 PDF 导出等。
下载地址：
5.EpicEditor
EpicEditor 是一个可嵌入式的 JavaScript Markdown 编辑器，提供全屏编辑、在线预览、自动保存草稿和离线编辑支持。对开发者提供可可靠的
API 做风格设置。
下载地址：
6.CuteMarkEd
CuteMarkEd 是一个 Markdown 编辑器，提供实时 HTML 预览、数学表达式和源码高亮。
下载地址：
MarkPad 是款开源的 Markdown 编辑器，与 Window 8 风格和谐友好的界面，可以直接在你的博客或者 GitHub 中打开、保存文档，直接将图片粘贴到 Markdown 文档中。
下载地址：
8.Haroopad
Haroopad 是一款覆盖三大主流桌面系统的编辑器，支持 Windows、Mac OS X 和 Linux。 主题样式丰富，语法标亮支持
54 种编程语言。该工具重点推荐 Ubuntu/Linux 用户使用，从此可以告别 gedit 加 Markdown 插件这种工作方式了。
下载地址：
9.MarkdownEditor
MarkdownEditor 是一款基于浏览器的 Markdown 文本编辑器，功能非常简单实用。
在线地址：&10.QMarkdownerQMarkdowner是一款基于PyQt4的markdown编辑器，支持实时编辑与实时预览和全屏预览。
下载地址：
推荐阅读相关主题：
CSDN官方微信
扫描二维码,向CSDN吐槽
微信号：CSDNnews
相关热门文章如何才能写出简洁好看的API文档，有没有开源框架可以用？
本人正在做一个开放平台，需要为本平台写一些API文档。 我曾经试图用markdown来写，但是markdown对code模块，table支持不好，也不支持一些人性化的设置。是需要手写CSS，html吗？但是我不是一个专业的前端开发人员，有没有开源框架可以用？我觉得写的好看的API文档：
按时间排序
swagger ，还能调试 API，我们在用。demo：
LeanCloud 的文档项目是开源的：如果你喜欢类似的结构可以 fork 一份自己去改。
ShowDoc是什么每当接手一个他人开发好的模块或者项目，看着那些没有写注释的代码，我们都无比抓狂。文档呢？！文档呢？！Show me the doc ！！程序员都很希望别人能写技术文档，而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版，想着新建的word文档放在哪个目录等各种非技术细节。word文档零零散散地放在团队不同人那里，需要文档的人基本靠吼，吼一声然后上qq或者邮箱接收对方丢过来的文档。这种沟通方式当然可以，只是效率不高。ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。它可以用来做什么API文档（ ）随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供API，APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。数据字典（ ）一份好的数据字典可以很方便地向别人说明你的数据库结构，如各个字段的释义等。说明文档你完全可以使用showdoc来编写一些工具的说明书。也可以编写一些技术规范说明文档以供团队查阅它都有些什么功能分享与导出响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。权限管理公开项目与私密项目ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码验证访问。密码由项目创建者设置。项目转让项目创建者可以自由地把项目转让给网站的其他用户。项目成员你可以很方便地为ShowDoc的项目添加、删除项目成员。项目成员可以对项目进行编辑，但不可转让或删除项目（只有项目创建者才有权限）编辑功能markdown编辑ShowDoc采用markdown编辑器，无论是编辑还是阅读体验都极佳很棒。如果你不了解Markdown，请在搜索引擎搜索”认识与入门 Markdown”模板插入在ShowDoc的编辑页面，点击编辑器上方的按钮可方便地插入API接口模板和数据字典模板。插入模板后，剩下的就是改动数据了，省去了很多编辑的力气。历史版本ShowDoc为页面提供历史版本功能，你可以方便地把页面恢复到之前的版本。部署到自己的服务器克隆或者下载代码：导入数据库下载代码后，将跟目录的showdoc.sql文件导入mysql数据库修改配置文件进入Application/Common/Conf/目录，编辑config.php文件，填写相应的数据库信息目录权限请确保Application/Runtime 有可写权限使用在线的ShowDoc如果你没有自己的服务器，但又想使用ShowDoc作为分档分享工具，你可以使用在线的ShowDoc
之前花了一个星期自己做了个：当然，这个本来是用做某个网站的前端框架的。其组件之一ML，就是代替Markdown的（语法更简单更严谨，功能更强大，就是写起来更丑陋，感觉在写TeX）。内部实现用了peg.js生成了叫JHTML的AST，然后再用这个AST重新生成HTML，同时也等于做了XSS防御。ML使用语义级别的标签，表格基本等于写HTML（复杂的跨栏表头均可以生成），code高亮，数学公式，图文混排，emoji都有了。ML展示（此页面的HTML均由ML生成）+ 手册：
我见过的最好看的API文档是Extjs的官方文档。是用Jsduck生成的
如果是 JavaScript， 推荐一个文档生成工具 FireDoc，基于 YUIDoc 进行了大幅改善：可以使用模板直接输出 HTML 页面，也可以输出 markdown 文件。是我们为自己的游戏引擎项目 Fireball
的文档生成打造的，相比 YUIDoc 更适用于规模较大和较为复杂的工程化项目。开发者是
不知道可不可以用gitbook来写……我瞎说的
Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。
比较好用的是swagger-ui, 可以使用swagger editor来编写。此外slate api编辑器也不错。slate demo()以上是编辑器。你想在你的项目中自动生成，那么得需要相关的插件。我做rails开发的，使用swagger，那么有swagger docs for rails插件，其他语言的自行搜索。rails项目中apipie rails也不错。这里的编辑器不支持md，自己格式化一下。#### articles1. [standard json api]()2. [api doc tools]()#### 我们公司的json格式```ruby{
status: 'success/fail/error',
code: 404,
msg: 'Unable to communicate with database',
data: { # or data: nil
next: '[offset]=2',
last: '[offset]=10'
}}```#### 相关链接1. [slate]()2. [apipie rails]()3. [swagger ui]()4. [swagger editor]()5. [air blue print]()6. [api ary]()7. [swagger docs for rails]()8. [api taster for test]()
原来API文档还可以这么屌！Apiary还开源了APIBlueprint，可以用markdown写文档，还可以通过中间工具发布到Github pages。
你需要Sphinx！！！Python的官方文档就是用这个写的。不过注意这个Sphinx是一个文档编写工具而不是那个有名的全文检索引擎。Sphinx使用reStructuredText 标记语法（和其他一些语法）来提供文档控制。reStructuredText 和Markdown类似，但是功能更为强大。更为方便的是，网上有一个网站提供rst的在线编辑器，地址为，你可以像使用编辑器一样来编写你的API文档，然后复制到Sphinx项目中去就行了。最后make html一下就生成了静态网页的文档，还能选择或者自定义模板。参见：注意官网被墙了，要翻墙才能上，但是网上有基本翻译好的文档。
apiblueprint，使用markdown编写，有很多前端生成html的工具。
你需要python的markdown模块，在扩展里有你想要的东西
api不仅要能看，还要能测，这样才能持续维护。
简单的文档当然是markdown最快，至于觉得table难打，请用。当然，markdown蛋疼的地方我也觉得很烦，真不爽的话自己写一个解析器如何，扩展点好玩的语法。假如markdown解析器不想写，咱们还能学reStructuredText，这货和markdown语法倒是接近，不过功能丰富太多了。用sphinx就能快速生成各种格式，sublime在装插件后，表格什么的完全不同自己打。想看效果的话，移步。再不济的话，用office吧。
我记得github的markdown对code和table的支持都挺好啊
已有帐号？
无法登录？
社交帐号登录IBM Bluemix
点击按钮，开始云上的开发！
developerWorks 社区
Project Zero 是一个简化的开发平台，侧重于遵从面向服务架构（Service-Oriented Architecture，SOA）的 Web 2.0 应用程序的敏捷开发。在诸多 Project Zero 库中包含一个简化的 API，可用来执行 SQL 查询。通过本文，学习如何利用 API 构建简单的 wiki。
(), IT 架构师, IBM Japan
Hanumanth Kanthi 是 IBM Software Services for WebSphere 的一名 IT 架构师。他拥有澳大利亚 Victoria University of Technology 的计算机科学硕士学位。您可以通过
与他联系。
开始之前 本文假设您对
已基本了解。要想加快进度，不妨先阅读一下介绍性文章 “” 和介绍性教程 “”。熟悉了 Project Zero 之后，就可以下载它（参见 ）并编写简单的应用程序。简介Larry Wall 的那句话真棒：让容易的事情保持容易，让困难的事情变得可能。
数据访问方面的用例既有简单的也有非常复杂的。因此，很多开发人员都希望获得一种足够灵活的数据访问 API，这种 API 既能处理复杂情形，又能使简单情形不会变得过于复杂。Project Zero 的数据访问 API（称为 zero.data）恰好能满足这个需求。它不是一种类似于 Hibernate 或 Java™ Persistence Architecture 的抽象层，而是一种库，力求通过提供一种围绕 SQL 的瘦包装器来 “让容易的事情保持容易，让困难的事情变得可能”，本文在稍后将会阐述。例如，清单 1 显示了如何执行一个简单的查询并获得由一列 bean 实例组成的结果：清单 1. 使用 zero.data 返回一列 bean 和映射实例Manager data = Manager.create("myDb");
List&Person& results = data.queryList("SELECT * FROM person", Person.class);
List&Map&String,Object&& resultsMap = data.queryList("SELECT * FROM person");在过去的一年中，Project Zero 团队一直与 IBM® 的 Information
Management 开发人在 pureQuery 技术上进行紧密合作，pureQuery 是一种高性能的数据访问平台，包括开发工具、API 和面向 Java 应用程序的高级运行时。zero.data 利用了 pureQuery 的 API 和运行时。zero.data 也支持使用 pureQuery 的工具集，因为 pureQuery 工具能生成 Java 工件。但在写作本文时，还没有该健壮工具集的特定于 Project Zero 的集成（有关 pureQuery 的更多信息，可以参考 ）。
图 1 显示了 Project Zero 的 API 和 pureQuery 之间的关系：
图 1. Project Zero 的 zero.data 关系数据访问 API 之间的关系
zero.data 围绕 pureQuery API 和运行时的功能提供了一种瘦包装 API。如果要在 Project Zero 应用程序中支持某些简化的假设（比如，配置和连接池化），以及提供公用的 API 以便 Groovy 和 PHP 脚本都能以对各自语言有益的方式利用健壮的 API，那么使用它要比使用 pureQuery API 更合适。比如，在 Groovy 接口中公布的一些方法都使用闭包，而其 PHP 对等物则使用 PHP 资源标识符。
本文主要介绍 Groovy API。有关 Java 和 PHP API 的更多信息，可以参阅 Project Zero 文档。在本文的剩余部分，您会了解在 Zero 应用程序中使用 zero.data 的基本知识。首先，您将学习使用 zero.data.groovy.Manager 接口管理数据，并了解其设计背后的动机，包括从 Java 和 Groovy 两个角度来看待 API 。接下来，您会立即开始实践，创建一个应用程序来使用 zero.data API。应用程序创建之后，将会构建一个简单 wiki、初始化表和最终完成该应用程序的代码。大概步骤如下所示：
管理数据zero.data.groovy.Manager（以下均简称为 Manager）定义了一种方便的 API，用户可使用它查询和操纵关系数据库。此 API 最基本的用法是传递 SQL 字符串。在 Groovy，传入的是嵌入在字符串内的参数，如下所示：data.queryFirst("SELECT * FROM t WHERE id=$id")。
Manager 然后使用
PreparedStatement 准备此字符串、执行它并返回结果。它还能智能地管理所创建的相关资源（closing resource）：比如结果集、语句和连接。
Manager 提供了一系列方法来执行如下操作：
执行查询并在每个执行闭包的行上进行迭代。
执行查询并只返回已转变成如下形式的 ResultSet 的第一行：
Java Bean 类的实例java.util.Map
执行查询并通过以下形式返回 ResultSet 中转变为上述形式之一的所有行：
java.util.Iteratorjava.util.ListJava 数组执行查询并返回 ResultSet。
执行数据操纵语言语句（比如 INSERT、UPDATE 和 DELETE），包括一种针对生成的键的特殊方法。
就数据而言，很有必要看看 Manager
如何减少样板代码，以及使您专注于功能而不是包含很多 bug 的代码。例如， 展示了
所示代码的纯 JDBC 实现，展示了 Manager 如何显著地让简单的事情变得容易：清单 2. 使用 JDBC 返回 Map 的一个实例更为繁琐// assumes Connection has already been initialized
// see JDBC documentation for more details
List&Map&String,Object&& results = new ArrayList&Map&String,Object&&();
PreparedStatement stmt =
connection.prepareStatement("SELECT * FROM person");
ResultSet rs = stmt.executeQuery();
while(rs.next()) {
ResultSetMetaData meta = rs.getMetaData();
int numColumns = meta.getColumnCount();
Map&String,Object& row = new HashMap&String,Object&(numColumns);
for (int i = 1; i &= numC i++) {
row.put(meta.getColumnName(i).toLowerCase(), rs.getObject(i));
results.add(row);
} finally {
rs.close();
} finally {
stmt.close();
实际上，应用程序代码很少像
所示的那样直接利用 JDBC。大多数框架都在某种程度上提供了一个间接和简化层。我们相信 Manager
能够很大程度地让简单的事情变得容易，让困难的事情成为可能。比如，除了能返回单一实例或 Java bean 类或 Map 的 List、Iterator 或 Array（如
所示）之外，zero.data 还提供了一个模板方法途径，允许开发人员或可能的第三方实现复杂 ResultSet 处理。
模板方法途径的更高级的用法将会在后续的 developerWorks 文章中讨论。正如之前提到的，zero.data 构建在 pureQuery 运行时引擎之上。pureQuery 运行时不仅提供了一种框架，通过一种开放 API 以可预见的灵活方式约束对数据库的访问，而且还鼓励代码的高度重用。比如，pureQuery 运行时本身主要由一些接口的实现组成，而这些接口是开发人员为了扩展该引擎而实现的。这样，pureQuery 运行时就能足够灵活地处理任何情况，从针对某个给定应用程序而对其引擎进行一次性扩展到采用可重用的 ResultSet 处理组件库的机构。
所示，Manager
实际上包装了 zero.data.Manager，提供了更多的 Groovy 友好的捷径。Manager 的数据访问 API 和 zero.data.Manager 的 API 的比较如下。您将会注意到二者都具有共同的主题。也就是说，很多方法类型完成的任务几乎相同，只不过针对特殊的用例。比如，queryList 返回 java.util.List，而 queryIterator 返回 java.util.Iterator。这很容易理解。这些方法类型中的每一个都具有三个重载方法，这些方法类型中的每一个都具有三个重载方法，这些方法类型中的每一个都具有三个重载方法，而且在签名和函数上是对称的。表 1 列出了所有的方法类型和重载方法，以及相关描述。可以在 Project Zero 的 Javadoc API 文档中找到更多信息。
表 1. Manager 方法的高层概览方法描述变量Groovy 中的对等物 queryFirst返回 ResultSet 中的第一行。Map&String,Object& queryFirst(String, Object...)Map&String,Object& queryFirst(GString)T queryFirst(String, Class&T&, Object...)T queryFirst(GString, Class&T&)T queryFirst(String, RowHandler&T&, Object...)T queryFirst(GString, RowHandler&T&)queryList将 ResultSet 作为 java.util.List 返回。List&Map&String,Object&& queryList(String, Object...)List&Map&String,Object&& queryList(GString)List&T& queryList(String, Class&T&, Object...)List&T& queryList(GString, Class&T&)List&T& queryList(String, RowHandler&T&, Object...)List&T& queryList(GString, RowHandler&T&)queryIterator将 ResultSet 作为 java.util.Iterator 返回。Iterator&Map&String,Object&& queryIterator(String, Object...)Iterator&Map&String,Object&& queryIterator(GString)Iterator&T& queryIterator(String, Class&T&, Object...)Iterator&T& queryIterator(GString, Class&T&)Iterator&T& queryIterator(String, RowHandler&T&, Object...)Iterator&T& queryIterator(GString, RowHandler&T&)queryArray将 ResultSet 作为 Java 数组返回。Map&String,Object&[] queryArray(String, Object...)Map&String,Object&[] queryArray(GString)T[] queryArray(String, Class&T&, Object...)T[] queryArray(GString, Class&T&)T[] queryArray(String, RowHandler&T&, Object...)T[] queryArray(GString, RowHandler&T&)update
执行更新并返回受影响的行数。
int update(String, Object...)int update(GString)insert执行并返回所生成的键值，该键值已强制转型成在第二个参数中指定的类。Groovy 的对等物则将其强制转型成 int。
T insert(String, Class&T&, String[], Object...)int insert(GString, List&String&)Java
编程和 Groovy
所展示的，zero.data 具有一个全面的数据访问方法集合，足以适应各种情况。我们只使用
zero.data.groovy.Manager 版的
queryFirst(GString)、queryList(GString)、 update(GString) 和 insert(GString, List)。
Groovy 是一种运行于 Java 平台上的面向对象的动态编程语言。有一种误解认为 Groovy 试图取代 Java 编程语言。由于 Groovy 会编译成 Java 字节码，所以它能利用标准的 Java API 和很多用 Java 语言编写的库。因此，Groovy 无意取代 Java 语法，而是提供一种包含很多语言结构的语法作为 Java 语法的补充，从而使代码更简洁紧凑。
比如，正如之前所演示的，使用 Java 版的 Project Zero 的 zero.data API，可以减少标准 JDBC 方法调用中的代码行。清单 3 对功能上等价的 Java 和 Groovy 代码进行了比较：
清单 3. 功能上等价的 Java 和 Groovy 代码的对比// Java
Manager data = zero.data.Manager.create("wiki");
data.inTransaction(new LocalTransaction() {
public void execute() {
data.update("UPDATE mytable SET name=? WHERE id=?", 1, "new name");
data.insert("INSERT INTO anothertable (name) VALUES (?)", "another name");
List&Map&String,Object&& results = data.queryList("SELECT * FROM sometable");
for (Map&String,Object& row : results) {
for (String key : row.keySet()) {
System.out.println("key: " + key + ", value: " + row.get(key));
def data = zero.data.groovy.Manager.create("wiki")
data.inTransaction {
data.update("UPDATE mytable SET name=$name WHERE id=$id")
data.insert("INSERT INTO anothertable (name) VALUES ($name)")
data.eachRow("SELECT * FROM sometable") { row -&
row.each { key, value -&
println("key: $key, value: $value")
从清单 3 可以看出，不仅代码行数减少了，而且 Groovy 语言似乎也显得比较灵活。比如，在 Java
版的 inTransaction 方法中，我们必须显式地创建 LocalTransaction 的一个匿名实例。但是，在 Groovy 中，我们将此隐藏于闭包之后。闭包是一种在 Groovy 内创建 “可移植” 代码的方法。与用 Java 语言创建抽象 LocalTransaction 类的匿名实现并将其传递给 inTransaction 方法类似，在 Groovy 中，可以以一种更为简洁的方式对闭包大括号（“{” 和 “}”）间的代码进行压缩并将其发送到 inTransaction 方法。Groovy 文档（参见 ）对 Groovy 中的闭包进行了更为全面的解释，包括示例以及如何编写将闭包作为实参的 API。
清单 3 中的代码的 Groovy 版给出了对闭包的第二和第三次使用。eachRow 方法可以接受闭包，并执行每一行结果中的大括号之间的代码。正如从清单中可以看到的，该代码调用了另一个闭包，此闭包只对行 Map 中的条目进行循环并打印输出键和值。
创建应用程序在本文的剩余部分，将使用典型的 Model-View-Controller 模式创建一个简单的 wiki，从而让您领略到 zero.data 所能提供的强大功能。图 2 展示了在 Zero 应用程序中实现这一目的的高层架构；在本文稍后，我们将介绍在何处放置代码工件以支持 Zero 约定。
Model-View-Controller 模式图 2 展示了 Project Zero 应用程序中的 Model-View-Controller 实现：
图 2. Project Zero 应用程序中的 Model-View-Controller 实现
要启动您的应用程序，首先需要创建一个 Project Zero 应用程序。后续的图展示了针对 Eclipse 的 Project Zero 插件的使用，这些插件提供了开发应用程序的用户界面捷径（但也可以使用命令行实用工具的类似功能实现同样的目的）。
首先，必须创建一个 Zero 应用程序。 给出了使用 Project
Zero Eclipse 用户界面创建应用程序的详细步骤，此外，还详细介绍了构成 Project Zero 应用程序的各种文件夹和工件。但是此处只介绍一些基础步骤。
单击 File & Project.. 菜单项创建应用程序。在随后出现的对话框中，可以选择项目向导。选择 Project Zero & Project Zero Application 启动向导，如图 3 所示：
图 3. 选择 Project Zero Application 向导
向导的第一个屏幕提示输入应用程序名称。该名称可以任意命名，如图 4 所示，我们将其命名为 mywiki：
图 4. New Project Zero Application 名称提示
这会在 Project Zero 应用程序文件夹结构的 Eclipse 工作区创建一个项目和一些默认的应用程序工件。找到 mywiki 项目。它应该如图 5 所示：
图 5. Project Zero 应用程序文件夹结构
由于 Project Zero 使用了 Ivy 框架来维持依赖项，因此很容易获得 zero.data。依赖项在应用程序的
${app_home}/config/ivy.xml 中声明。为了简便起见，我们使用嵌入模式的 Apache Derby 进行演示。对此文件进行编辑使其包括清单 4 中给出的那两行 XML：
清单 4. 添加到应用程序的 ivy.xml&dependency org="zero" name="zero.data" rev="1.0+"/&
&dependency org="org.apache.derby" name="derby" rev="10.3.1.4"/&
“” 对新的依赖项进行解析，然后再返回这里。
配置 zero.datazero.data 使用 javax.sql.DataSource 连接到数据库。可以在 Project Zero 应用程序的 zero.config 文件中配置连接属性，从而配置并连接到一个或多个数据库。清单 5 给出了如何使用 “wiki” 键配置给定的数据库：
清单 5. 在 zero.config 中配置 zero.data/config/db/wiki = {
"class" : "org.apache.derby.jdbc.EmbeddedDataSource",
"databaseName" : "db/wiki",
"connectionAttributes" : "create=true"
} 获取 Manager 实例
配置好数据库连接属性之后，就可以获取 Manager 实例了。利用这个实例，可以使用之前介绍的简便方法执行查询并操纵数据。我们使用在 zero.config 文件中选择的键获取经过配置的 Manager。在本例中，我们选择了 'wiki'。将它作为实参传递给 create 方法，如清单 6 所示：
清单 6. 获取经过配置的 Managerdef data = zero.data.groovy.Manager.create('wiki')
正如从 、 和
中看到的，仅需非常少的操作就能启动并运行 Zero 应用程序。接下来，我们将定义一些基本要求并将其转换为代码，从而构建一个简单的 wiki。
构建一个简单的 wiki 为了说明 zero.data 的使用，我们将构建一个简单的 wiki 应用程序。在其最简单的形式中，wiki 创建、编辑、链接并呈现 wiki 页面。因此，在这个示例中，我们将说明规范 CRUD 操作中的 Create、Retrieve 和操作（但未说明 Delete 操作）。
为什么用 wiki? 为什么要实现一个 wiki 来说明 zero.data API 呢？首先，wiki 非常简单。因此，我们可以将重点始终放在 zero.data API 上，而不用将过多精力花在实现复杂 wiki 所需的细节上。其次，wiki 提供了一个很好基础，以后可以在此基础上构建额外的功能以演示更高级的 zero.data 用法以及 Project Zero 的其他特性。
Wiki 需求如前面提到过的，一个基本的 wiki 实现需要创建、检索并更新 wiki 页面。大多数 wiki 实现都有一个共同点，那就是 wiki 页面首先要通过链接到其他页面来创建。wiki 用户单击这样的一个链接，会出现一个表单，提示用户创建 此页面。如果这个页面已经存在，它就会与一个链接共同呈现，此链接允许用户在与创建表单类似的表单中编辑这个页面。
我们将结合使用 Project Zero 的脚本和模板特征，并利用一些熟悉的 MVC 模式技巧将此实现原型化。也就是说，我们将会把控制器脚本放到应用程序的公共文件夹中。可以通过 URI 访问这些脚本 — 类似于 PHP 应用程序。文件系统的文件夹层次结构及文件与 URI 结构相匹配。我们的视图保存于应用程序的 /app/views 文件夹。由于要在 Groovy 中进行实现，因此控制器都会具有 .groovy 后缀，并且视图也会被加上 .gt 后缀。
为了更好地了解目前的进度，图 6 显示了创建应用程序工件后将会得到的应用程序目录。
图 6. 完成这些步骤后的 Project Zero 应用程序文件夹结构
需要了解的背景知识已经足够了，现在我们开始研究代码。
初始化表在深入介绍控制器和视图实现之前，我们需要一个用来检索、显示和操纵数据的模型。我们将在一个数据库表中保持 wiki 页面。为简单起见，我们的模型只是映射到数据库表中的某一行的一个 Map（如果不这样，那么这就不是一篇侧重介绍 zero.data
的文章了）。我们对存储的需求不大。只需要页面的名称和实际页面内容。如清单 7 中（放在 setup.sql 文件内）给出的 SQL 代码片段所示：
清单 7. setup.sql 的内容CREATE TABLE pages (
id int NOT NULL GENERATED ALWAYS AS IDENTITY (START WITH 1, INCREMENT BY 1),
name varchar(20) NOT NULL,
content varchar(3000),
updated timestamp,
PRIMARY KEY
);启动应用程序！与前面讨论过的其他应用程序工件不同，这里没有关于 setup.sql
的约定。包括在此文件中的数据定义由一个启动处理程序执行 — 提供给 Project Zero 应用程序的代码，在应用程序启动之后的某个阶段执行。
首先，我们创建当 Project Zero 应用程序启动时将要执行的 Groovy
脚本。如果数据库不存在，我们希望该脚本执行在 setup.sql 中找到的语句。我们将采用一个开发时的小技巧，但请不要在产品环境中使用。目前还不支持实时修改现有的数据库模式。因此，如果应用程序的模式改变了，必须使用启动处理程序将此数据库从文件系统中删除。为了演示的需要，我们首先演示最佳实践。但这个简单的实现足以说明 zero.data API 的用法（参见清单 8）：
清单 8. app/scripts/startup.groovy 的内容import zero.data.groovy.Manager
//if derby database already exists, don't run the script
def db_dir = new File('db/wiki')
if (!db_dir.isAbsolute())
db_dir = new File(config.root[], 'db/wiki')
if (!db_dir.exists()) {
def buffer = new StringBuffer()
new File('setup.sql').text.split('\n').each() { line -&
line = line.trim()
if (line && !line.startsWith("--") && !line.toLowerCase().startsWith("connect"))
buffer && line && '\n'
def statements = buffer.toString().split(';')
def data = Manager.create('wiki')
data.inTransaction() {
statements.each() { statement -&
statement = statement.trim()
if (statement)
data.update(statement)
} catch (Throwable error) {
throw new RuntimeException("Setup database error: ${error.message}", error);
}要在启动时执行这个脚本，还需要进行相关的配置。方法是在 config/zero.config 文件中将此脚本作为启动处理程序注册，如清单 9 所示：
清单 9. 将以下内容添加到 config/zero.config/config/handlers += {
"events" : "start",
"handler" : "startup.groovy"
}这个注册告诉 Project Zero 运行时只要 “start” 事件被激发，无论处于何种情况都要执行 startup.groovy 脚本。启动 Project Zero 应用程序，现在 CREATE TABLE 语句将被执行。因为数据库尚不存在，嵌入式 Derby 将在磁盘上创建一个数据库（因为在之前配置连接属性时，设定了当数据库不存时就创建一个数据库）。
编写应用程序让应用程序保持运行。Project Zero 是动态的并且可以检测到绝大多数更改。现在，表单已经创建了，可以开始为控制器和视图编写代码了。让我们从呈现一个页面开始。
呈现动态 HTML　要呈现一个页面，我们需要一个 hook，Project Zero 运行时利用它将控制权转交给 wiki 应用程序。我们将以一个控制器的形式在 app/public 目录中实现这一目的。我们将调用呈现功能 “view.groovy”。首先，需要一个 Manager 执行页面查询。接下来，我们将执行一个查询来检索数据库中的某一行。如果此行存在，我们就呈现它。如果不存在，就显示一个创建页面。此实现如清单 10 所示：清单 10. view.groovy 实现def name = request.params.name[]
def data = new zero.data.Manager('wiki')
def page = data.queryFirst("SELECT * FROM pages WHERE name=$name")
if (page) {
request.page.name = page.name
request.page.content = page.content
request.view = 'view.gt'
request.page.name = name
request.view = 'create.gt'
render()我们现在需要创建 'view.gt' 与 'create.gt' 视图来支持 view.groovy
控制器。两个视图均使用 Groovy 模板在请求范围呈现数据（参见清单 11 和 12）：
清单 11. view.gt 实现&html&
&title&&%= request.page.name[] %&&/title&
&h1&&%= request.page.name[] %&&/h1&
&%= request.page.content[] %&
&a href="&%= "${getRelativeUri('/edit.groovy')}?page=${request.page.name[]}" %&"&
Edit this page?
&/html&清单 12. create.gt 实现&html&
&title&&%= request.page.name[] %& - Create&/title&
&h1&&%= request.page.name[] %&&/h1&
This page does not exist.
&a href="&%= "${getRelativeUri("/edit.groovy")}?name=${request.page.name[]}" %&"&
&/html&更新数据库我们在前面的章节中创建了两个视图：一个被呈现的 wiki 页面和一个创建 wiki 页面的表单。为了支持这些视图，还需要创建另外的控制器和视图。也就是说，view.gt 视图链接到 edit.groovy 控制器，create.gt HTTP 通过呈现 edit.gt 将其表单 POST 给 save.groovy。edit.groovy 检索数据并显示一个与创建表单类似的表单，只不过，这里的表单是用已存在的 wiki 页面内容填充的。save.groovy 向数据库表中插入一行或更新一个已存在的行。清单 13 到 15 显示了它们的实现：
清单 13. edit.groovy 实现def name = request.params.name[]
def data = zero.data.groovy.Manager('wiki')
def page = data.queryFirst("SELECT COUNT(*) FROM pages WHERE name=$name")
if (page) {
request.page.content = page.content
request.page.content = ""
request.page.name = name
request.view = 'edit.gt'
render()清单 14. edit.gt 实现&html&
&title&&%= request.page.name[] %& - Editing&/title&
&h1&Editing &%= request.page.name[] %&&/h1&
&form method="POST"
action="&%= "${getRelativeUri('/save.groovy')?name=${request.page.name[]}" %&"&
&textarea name="content" rows="20" cols="60"&&%= request.page.content[] %&&/textarea&
&input type="submit" value="Save Page"/&
&/html&清单 15. save.groovy 实现def name = request.params.name[]
def data = zero.data.groovy.Manager('wiki')
def page data.queryFirst("SELECT * FROM pages WHERE name=${name}")
def content = request.params.content[]
if (page) {
data.update("UPDATE pages SET content=${content}")
data.update("INSERT INTO pages (name,content) VALUES ($page_name,$content")
uri = "${getAbsoluteUri('/view.groovy')}?name=${name}"
request.headers.out.Location = uri
request.status = HttpURLConnection.HTTP_MOVED_TEMP测试应用程序您现在拥有了一个基本的 wiki 应用程序。由于它非常简单，所以必须提供一个不存在的 wiki 页面引导应用程序。输入 http://localhost:8080/view.groovy?name=HomePage 可以实现此操作，从而得到图 7 所示的页面：
图 7. 缺失主页
系统提示页面不存在。这很好，因为它说明应用程序正在工作。我们可以给 URI 的名称参数任意赋值，比如 “HomePage” 就不错。接下来，需要为主页创建内容。输入任意 HTML。还可以在表单中添加一个链接到其他页面（即使我们知道该页面并不存在，也可以添加）的链接，如图 8 所示：
图 8. 编辑主页
现在，我们单击 Save Page 按钮将页面保存到数据库。然后重定向以查看我们刚刚编辑过的页面，如图 9 所示：
图 9. 找到主页
如果链接到了一个不存在的页面（这很容易发生，因为此时数据库中只有一个页面），那么单击此链接，就会再次跳转到缺失页面屏幕。您可以为所链接的页面创建一个页面，如图 10 所示：
图 10. 缺失 CodingTips
以上就是有关创建简单 wiki 应用程序的全部内容。自然，我们的 wiki 还可以做更多事情。比如，可以用诸如 Markdown 或 Textile 这样的标记文本简化内容的创建和链接，以及其他操作。（您可以在以后将这些作为练习！）
结束语Project Zero 是一个简化的开发平台，侧重于遵从 SOA 的 Web 2.0 应用程序的敏捷开发。在诸多 Project Zero 库中包含一个简化的 API，可用来执行 SQL 查询。通过本文，学习了如何利用 API 构建简单的 wiki。
我们讨论了 zero.data API 背后的机制，包括它对 pureQuery API 的包装。我们还深入探讨了 zero.data.Manager，并给出了 Java 和 Groovy 版的 API 间的高层次的差异。然后通过使用 zero.data API 创建应用程序进行实践，包括构建一个简单 wiki、初始化数据库表，以及最终对该实现进行编程。希望本文会对您有所帮助，并且会激发您尝试创建 Zero 应用程序的兴趣！活跃的
会在您需要的时候为您提供帮助。
下载描述名字大小Project Zero Eclipse 示例项目10KB
参考资料 您可以参阅本文在 developerWorks 全球站点上的
。“”（developerWorks，2007 年 10 月）对 Project Zero 在创建、编译和部署功能强大的 Web 应用程序方面的创新进行了总体介绍。
”（developerWorks，2007 年 11 月）讨论了 Project Zero 是如何让应用程序资源基于访问控制的安全性变得如此简单的。
”（developerWorks，2007 年 11 月）介绍了如何防御常见的基于 Web 2.0 的应用程序攻击（比如跨站点脚本编写），以及如何使用 Active Content Filtering 提高 Project Zero 应用程序的安全性。
是一个开发工具、应用程序运行时 API 和管理 Java 数据库开发生命周期的引擎的健壮组合。Project Zero 利用运行时 API 和引擎提供灵活的 Web 2.0 应用程序开发环境。
展示了在 Groovy 中利用此高级语言结构的一些实用方法。
“”（Wikipedia，2007 年 11 月）讨论了这种模式，以及软件库设计人员如何在设计 API 中使用它来支持用户向系统中注入新的功能，而且无需修改现有的服务。“”（developerWorks，2007 年 9 月）展示了管理跨多个 Project Zero 应用程序的数据库配置的技术。
更详细地描述了可用于数据库访问的所有方法。
并了解有关于 Project Zero 的方方面面。
有关 Project Zero 的介绍性教程 “” 可以让您立即开始开发 Project Zero 应用程序。
浏览 developerWorks
获得工具、代码和资源以便立即开始开发 Web 2.0 应用程序。
developerWorks
包含面向各种技能级别读者的信息，可帮助您将 Ajax 构建到自己的应用程序中并显著提高用户的 Web 体验。
并开始构建 wiki。
：一个聚集了大量与 Project Zero 和 IBM Web 2.0
技术相关的文章、论坛和 blog 的门户。
developerWorks: 登录
标有星（*）号的字段是必填字段。
保持登录。
单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件。
在您首次登录 developerWorks 时，会为您创建一份个人概要。您的个人概要中的信息（您的姓名、国家/地区，以及公司名称）是公开显示的，而且会随着您发布的任何内容一起显示，除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。
所有提交的信息确保安全。
选择您的昵称
当您初次登录到 developerWorks 时，将会为您创建一份概要信息，您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。昵称长度在 3 至 31 个字符之间。
您的昵称在 developerWorks 社区中必须是唯一的，并且出于隐私保护的原因，不能是您的电子邮件地址。
标有星（*）号的字段是必填字段。
(昵称长度在 3 至 31 个字符之间)
单击提交则表示您同意developerWorks 的条款和条件。 .
所有提交的信息确保安全。
文章、教程、演示，帮助您构建、部署和管理云应用。
立即加入来自 IBM 的专业 IT 社交网络。
为灾难恢复构建应用，赢取现金大奖。
static.content.url=/developerworks/js/artrating/SITE_ID=10Zone=Web development, XML, Information ManagementArticleID=284720ArticleTitle=用 Project Zero 的数据访问 API 构建简单 wikipublish-date=