Java 从入门到入土(三)注释与API文档的生成,如何生成api文档

本文讲述了Java 从入门到入土(三)注释与API文档的生成,如何生成api文档。

注释不参与代码编译与运行，当计算机执行到有注释符号注释的语句时会跳过它，执行下面没有被注释的语句。

通俗来讲是对所编写代码使用人类语言进行描述与解释，目的是使他人和自己更好地理解自己编写的程序。

API（Application Programming Interface，应用程序编程接口）抽象上说是软件系统不同组成部分的衔接约定。通俗上来讲就是人们写了一段代码，然后我们想要在别的地方使用这段代码，于是给这段代码定义了一个名字（API），我们在别的地方使用这个名字（API），就相当于运行了整段代码（对于API这里仅作简单介绍，对其特性定义阐述的也很不全面。如果想要深入了解可以自行查阅资料）。

（1）注释在Java中，注释有三种：

//   单行注释    将单行注释符后一整行的内容声明为注释，只能注释一行。

单行注释

/*.........*/   多行注释   将多行注释符中间的部分声明为注释。可以在注释符中注释多行。

多行注释

/**.......*/   文档注释 一般使用于变量，方法，接口以及类本身的前面。作用一是解释注释后的语句块的作用；二是便于生成Java API文档（其中的概念后面文章会一一介绍，现在可以先不做深入了解）。

文档注释的使用为：在要添加注释的语句块（语句块的本质就是一段代码）的上一行敲下/**接着按回车（Enter）键，这样就能生成一个相应语句块的文档注释。

文档注释你可以在其中填写其对应的语句块（main方法）的解释。其中@param arg 表示你可以在编写文档注释的时候添加args参数的解释。如下：

文档注释

（2）生成API文档

a.通过Eclipse生成API文档。

点击Project,选择Generate JavaDoc选项，进入如下界面。

设置Javadoc command路径为你安装jdk路径下bin文件夹下的javadoc.exe文件路径。

C:\Program Files\Java\jdk1.8.0_171\bin\javadoc.exe

勾选要生成文档的项目FFF。

接着设置文档生成级别（Create Javadoc for member with visibility ）

我们设置为private ，意思是会生成项目中的全部内容的API文档。接着是储存路径（Use standard doclet ）。可以进行修改，也可以使用默认。我们这里使用默认路径D：\test\FFF\doc

API文档生成设置点击Finish。可以看到控制台输出生成信息。在项目结构下多出了一个doc目录。里面存放的是文档的相关信息。

API文档目录结构

打开我的电脑，进入D:\test\FFF\doc目录下，双击index.html文件。就可以进入文档界面。doc文件夹

b.使用控制台命令生成API文档

首先我们在d盘的test文件夹中新建一个名为helloworld的txt文件，将注释过的helloworld程序代码粘贴进去。helloworld程序保存退出，将其修改为helloworld.java文件。在cmd界面进入test文件夹输入 javadoc -d doc helloworld.java命令。

这条命令的意思是在当前文件夹下新建doc文件夹，并在doc文件夹中生成API文档。

生成API文档

注：如果命令出错一般为文本文档编码格式出现问题。编码格式出错提示修改方式如下：网上下载一个文本编辑器。我这里使用的是Notepad++不要使用记事本的另存为来修改编码格式。因为记事本的UTF-8格式其实是UTF-8-BOM格式。使用记事本修改后会提示编码格式出错提示在文本编辑器下打开helloworld.Java文件，选择编码方式为UTF-8保存退出。

在cmd界面下更改命令为

javadoc -d doc -encoding UTF-8 helloworld.java

成功导出

成功通过命令行生成API文档

编写API文档是API编写人员的噩梦，而API文档通常是由API研发人员编写。由于API文档创建繁琐，需要记录的内容比较广，结束了API开发任务后，还要仔细编写API文档，给研发人员带来额外的工作量。

随着需求量越来越高，工具的诞生让API的研发与API文档之间的联系更加紧密。例如：Swagger、Eolinker、APIdoc、Easydoc等，这些API文档管理工具不仅可以生成漂亮的在线API文档，并且支持集成到项目自动生成API文档。

以Eolinker为例，Eolinker为用户提供了该工具的OpenAPI，方便用户集成到开发系统。在每个API开发完成后，快速调用OpenAPI并自动生成API文档。

当然OpenAPI不仅仅是自动新增API文档那么简单，Eolinker还提供了能快速对系统进行操作的OpenAPI，可集成到Jenkins等集成工具。有了这些OpenAPI，用户可以利用它们让整个开发流程更加”顺滑”，例如当开发完成触发OpenAPI进行测试等。

OpenAPI只是其中一个实现方式，一些工具则通过配置文件使用依赖的方式集成到开发系统。例如Swagger2就是以这种方式生成的API文档，并且Swagger2生成API的界面同样漂亮、简洁。

团队可以根据项目需求去挑选合适的API文档工具，若仅对API文档有需求，本文提及的四个工具（Swagger、Eolinker、APIdoc、Easydoc）都是不错的选择。如果考虑到项目需要优化整个API开发流程，并使用工具进行集成，可以选择一些功能强大，且容易集成到项目的API管理工具（Eolinker、APIdoc等）。
演示工具：www.eolinker.com

上述是小编为大家整理的Java 从入门到入土(三)注释与API文档的生成,如何生成api文档。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。