javaDoc
javaDoc是JDK提供的一款用于便携编写java文档的工具。通过在类、成员变量上编写javadoc文档,从而生成清晰易读的api文档。
javaDoc文档标记
javaDoc工具可以识别文档注释中一些特殊符号,这些符号一般以@开头。常见的javaDoc文档标记如下所示:
标签 | 作用 |
---|---|
@link | 标注对应的文档、类等的链接地址,使用时需要以{@link}的方式使用 |
@code | 标识特定的代码片段 |
@param | 该标记一般用于方法上,用于标注入参的结构类型和作用 |
@author | 标注作者名称。 |
@since | 标注类、方法名称出现的时间。 |
@see | 这个其实跟@link标记类似,都是用于标注某些特殊变量的标记符,但是@link能够结合文字展示,而@see不可以 |
@version | 主要是用于标注当前代码的版本信息 |
@deprecated | 用于标注当前的方法已经不推荐使用 |
@throw | 用于标注当前方法抛出的异常类型。 |
@inheritDoc | 用于继承父类中的javaDoc文档内容信息 |
@serial | 用于说明当前的一个序列化属性使用的 |
@value | {@value} 用于标注在常量上用于表示常量的值,主要是在注释中起到占位的作用 |
尽管javadoc本身包含的标记很多,但是实际上能用到的、常用的其实不多。这里我简要介绍几个:
@link
@link是一个十分好用的javadoc注解。其可以方便的在java代码中嵌入类名等信息。通过嵌入的类名,我们可以通过cmd+B的命令快速跳转到指定的对象。避免反复查找的问题。
@See
@see是最常用也最实用的注解之一。@see注解之后,可以添加任何的类名。根据提供的类名信息,IDEA可以直接跳转到对应的类。
这样的方式在设置某个参数的枚举类的时候尤其好用,再也不用翻找全局去确定一个枚举的具体取值了。
@Deprecated
deprecate顾名思义,是废弃的意思。常常会同JAVA的注解@Deprecated搭配使用,用于标注当前类/方法等被废弃的原因。
@Param
@param是最常见的标记符之一,一般用于标注出请求参数的含义。方便接口调用方快速理解接口。与之相似的,还有@Return标记符。@Return标记符则主要用于标记当前的返回参数的含义。
通过上述标记符号的结合,我们可以很容易的将一个接口的请求参数、功能很简单的描述出来。如下是我设计的一个有关分布式锁接口的Api接口文档:
对于这样的接口,你还会觉得有理解的成本嘛?
生成javadoc
通过编写javadoc,我们还可以生成相应的接口文档。通过选择特定文件夹后,从Tools=>Generate JavaDoc即可选择对应的文件生成javaDoc。
最后,我通过点击生成文件中的index.html即可获取到相应的接口文档信息。
Swagger
对于JavaDoc来说,个人觉得其针对的主要是相同采用JAVA编程后端设计的。但是在如今前后端分离的时代,跟前端的交互也是必不可少的。因此,如何输出清晰的文本文档给到前端同学,也是很重要的一环。而这正是Swagger的擅长之处。
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。swagger官网:swagger.io/按照规范定义接口以及接口相关的信息,通过swagger衍生的工具生成接口文档;以及在线调试页面等。
快捷接入
这里,我主要介绍一下JAVA下,Springboot框架是如何快速结合Swagger搭建接口文档的。首先必不可少的是需要引入相关的maven依赖信息:(需要注意,swagger跟springboot有一定的对应关系,可以查看该文章判断自己的版本是否对应:)
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
复制代码
紧接着,为了让Swagger能够正常运行起来,我们还需要添加相关的配置类:
@Configuration
@EnableOpenApi
@Profile({ "dev","test" })
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("xxx")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("基于 Swagger2 的自动化文档")
.version("1.0")
.build();
}
}
复制代码
当然还有一个步骤,需要在启动类上增加@EnableOpenApi的注解。至此Swagger的接入就基本完成了。通过在浏览器中输入网址: http://localhost:8080/swagger-ui/index.html#/就可以看到当前的文档信息。
如何使用
对于swagger来说,其主要通过在特定的类、方法和属性上添加注释实现接口文档的生成。Swagger本身涉及到的注解很多,这里限于篇幅原因,我主要介绍两个我在项目中最常用的注释: @ApiModelProperty和@ApiOperation。
@ApiModelProperty
该注解主要用于输入的参数属性上,用于描述参数的属性信息:
属性 | 作用 |
---|---|
value | 当前的属性名称 |
notes | 对于属性的描述信息 |
example | 属性的示例 |
required | 是否必须传递 |
@ApiOperation
该注解主要用于系统的对外接口参数上,用于描述接口的属性信息:
属性 | 作用 |
---|---|
value | 当前的属性名称 |
notes | 对于属性的描述信息 |
response | 返回的属性类型 |
httpMethod | 请求方式 |
总结
上文内容中主要介绍了两种编写接口文档的方式:javaDoc和Swagger。其中javaDoc由于其提示方式,更适用于后端间的接口编写。通过合适的javaDoc标记,可以很简单的标记出相关的枚举类、额外的文档信息等。
Swagger与javaDoc不同,其主要提供了一个在线的接口文档提供方式。在针对后端对前端提供文档的情况下,有较好的表现。通过简单的编写,就可以在项目启动后,提供一个完整的接口文档。
通过Swagger和javaDoc结合,我们就可以通过极少的代码,搭建出清晰易懂的接口文档。