还苦于写接口文档？快试试javaDoc和Swagger

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结合，我们就可以通过极少的代码，搭建出清晰易懂的接口文档。

参考文献

Javadoc 使用详解

Javadoc(文档注释)详解！！！

在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc

如何不运行项目，查看swagger接口文档