|
标签
|
作用
|
|
@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注解之后，可以添加任何的类名。根据提供的类名信息，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
该注解主要用于输入的参数属性上，用于描述参数的属性信息：
上文内容中主要介绍了两种编写接口文档的方式：javaDoc和Swagger。其中javaDoc由于其提示方式，更适用于后端间的接口编写。通过合适的javaDoc标记，可以很简单的标记出相关的枚举类、额外的文档信息等。
Swagger与javaDoc不同，其主要提供了一个在线的接口文档提供方式。在针对后端对前端提供文档的情况下，有较好的表现。通过简单的编写，就可以在项目启动后，提供一个完整的接口文档。
通过Swagger和javaDoc结合，我们就可以通过极少的代码，搭建出清晰易懂的接口文档。
Javadoc 使用详解
Javadoc(文档注释)详解！！！
在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc
如何不运行项目，查看swagger接口文档
