java api在线文档-java在线接口文档 收藏 0

Javadoc（文档注释）详解

Java 支持 3 种注释，分别是单行注释、多行注释和文档注释。文档注释以/**开头，并以*/结束，可以通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、成员变量和方法的功能。文档注释只放在类、接口、成员变量、方法之前，因为 Javadoc 只处理这些地方的文档注释，而忽略其它地方的文档注释。Javadoc 是 Sun 公司提供的一种工具，它可以从程序源代码中抽取类、方法、成员等注释，然后形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时以一套特定的标签注释，在程序编写完成后，通过 Javadoc 就形成了程序的 API 帮助文档。

API 帮助文档相当于产品说明书，而说明书只需要介绍那些供用户使用的部分，所以 Javadoc 默认只提取 public、protected 修饰的部分。如果要提取 private 修饰的部分，需要使用 -private。

Javadoc 工具可以识别文档注释中的一些特殊标签，这些标签一般以@开头，后跟一个指定的名字，有的也以{@开头，以}结束。Javadoc 可以识别的标签如下表所示：

对两种标签格式的说明：

• @tag 格式的标签（不被{ }包围的标签）为块标签，只能在主要描述（类注释中对该类的详细说明为主要描述）后面的标签部分（如果块标签放在主要描述的前面，则生成 API 帮助文档时会检测不到主要描述）。
• {@tag} 格式的标签（由{ }包围的标签）为内联标签，可以放在主要描述中的任何位置或块标签的注释中。

Javadoc 标签注意事项：

• Javadoc 标签必须从一行的开头开始，否则将被视为普通文本。
• 一般具有相同名称的标签放在一起。
• Javadoc 标签区分大小写，代码中对于大小写错误的标签不会发生编译错误，但是在生成 API 帮助文档时会检测不到该注释内容。

Javadoc 用法格式如下：

javadoc [options] [packagenames] [sourcefiles]

对格式的说明：

• options 表示 Javadoc 命令的选项；
• packagenames 表示包名；
• sourcefiles 表示源文件名。

在 cmd（命令提示符）中输入javadoc -help就可以看到 Javadoc 的用法和选项（前提是安装配置了JDK），下面列举 Javadoc 命令的常用选项：

新建一个空白记事本，输入下列代码：

将文件命名为 Test.java，打开 cmd 窗口，输入javadoc -author -version Test.java命令。如图 1 所示。

图 1 cmd 运行窗口

打开 Test.java 文件存储的位置，会发现多出了一个 Test.html 文档。打开文档，文档页面如图 2 和图 3 所示。

图 2 Student.html 页面（1）

图 3 Student.html 页面（2）

注意：以上没有考虑编码格式的问题，注释中有汉字可能会乱码。使用javadoc -encoding UTF-8 -charset UTF-8 Test.java会解决编码问题。

1）在 MyEclipse 中新建一个 Test 类，代码如下：

注意：代码 9~11 行没有放在类、成员变量或方法之前，所以 Javadoc 会忽略这个注释。2）在项目名处单击鼠标右键，然后选择Export…，如图 4 所示。

图 4

3）在弹出窗口中选择 Java 文件夹，点击 Java 文件夹下面的 Javadoc，然后点击“Next”，如图 5 所示。

图 5

4）选择你要生成 Javadoc 的项目，并更改你想保存的 API 帮助文档地址（默认为工程目录下，建议不要修改）。点击“Finish”，如图 6 所示。

图 6

5）点击“Finish”之后会问是否更新 Javadoc 文件的位置，只需要点击“Yes To All”即可，如图 7 所示。

图 7

6）这时可以看到控制台输出生成 Javadoc 的信息，如图 8 所示。

图 8

7）打开保存的文件夹，找到 Test.html 文件并打开，如图 9 所示。

图 9

以上就是使用 MyEclipse 简单建立一个 API 帮助文档的过程。

在编写文档注释的过程中，有时需要添加 HTML 标签，比如：需要换行时，应该使用<br>，而不是一个回车符；需要分段时，应该使用<p>。例如把上面 Test 类改为以下代码：

帮助文档格式如图 10 所示。

图 10

Javadoc 并不是将代码中的文档注释直接复制到帮助文档的 HTML 文件中，而是读取每一行后，删除前面的*号及*以前的空格再输入到 HTML 文档。

/*** first line.******* second line.* third line.*/

编译输出后的 HTML 源码如下所示。

first line. <br>second line. <br>third line.

注释前面的*号允许连续使用多个，其效果和使用一个*号一样，但多个*前不能有其他字符分隔，否则分隔符及后面的*号都将作为文档的内容。

SpringBoot 优雅整合Swagger Api 自动生成文档

一个好的可持续交付的项目，项目说明，和接口文档是必不可少的，swagger api 就可以帮我们很容易自动生成api 文档，不需要单独额外的去写，无侵入式，方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目，剩余的时间就可以去约妹子啦

这里我们自己去整合swagger api比较麻烦，要导入好几个包，有大神帮我们写好了轮子kinfe4j直接对应SpringBoot的启动项，而且在不影响原来使用功能上界面ui做了美化功能做了增强 我们直接整合这个就好了

正如官网所说

kinfe4j官方文档点击这里

为我们为swagger配置更多的接口说明

抽出api文档配置模版信息为属性文件方便复用

在你的Controller上添加swagger注解

注意如启用了访问权限，还需将swagger相关uri允许匿名访问

重启服务，自带api文档访问链接为/doc.html界面如下:

相比较原来界面UI更加漂亮了，信息更完善功能更强大

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数：

1. tags：说明该类的作用，参数是个数组，可以填多个。
2. value=\”该参数没什么意义，在UI界面上不显示，所以不用配置\”
3. description = \”用户基本信息操作\”

用于请求的方法上表示一个http请求的操作

参数:

1. value用于方法描述
2. notes用于提示内容
3. tags可以重新分组（视情况而用）

用于请求方法上对请求参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

参数：

1. name–参数名
2. value–参数说明
3. required–是否必填

用于java实体类上表示对类进行说明，用于参数用实体类接收

参数：

1. value–表示对象名
2. description–描述都可省略

用于方法，字段； 表示对model属性的说明或者数据操作更改

参数：

1. value–字段说明
2. name–重写属性名字
3. dataType–重写属性类型
4. required–是否必填
5. example–举例说明
6. hidden–隐藏

用于请求类或者方法上，可以不被swagger显示在页面上

用于方法表示单独的请求参数

用于方法，包含多个 @ApiImplicitParam

参数：

1. name–参数名
2. value–参数说明
3. dataType–数据类型
4. paramType–参数类型
5. example–举例说明

1. 可以给实体类和接口添加注释信息
2. 接口文档实时更新
3. 在线测试
4. kinfe4j 在swagger API只做增强，不会改变原有任何使用，更多增加使用功能点击这里进入kinfe4j官网文档

本文作者及来源:Renderbus瑞云渲染农场https://www.renderbus.com