自动化生成RestFul风格API的文档

作为后端人员，开发结束后写一份清晰明了的接口文档，有利于与客户端联调。笔者之前的公司使用的就是接口管理平台eolinker。但毕竟手写wiki也是件麻烦的事，下面介绍两款自动生成接口文档的工具jsondoc、swagger

Jsondoc

基于SpringBoot的用法步骤

• pom文件导入依赖

<dependency>
   <groupId>org.jsondoc</groupId>
   <artifactId>spring-boot-starter-jsondoc</artifactId>
   <version>1.2.19</version>
</dependency>
<dependency>
   <groupId>org.jsondoc</groupId>
   <artifactId>jsondoc-ui-webjar</artifactId>
   <version>1.2.19</version>
</dependency>

• 入口类添加注解@EnableJSONDoc
• 在controller类中添加Jsondoc相关注解

package com.huanmeiqi.jsondoc.controller;

import com.huanmeiqi.jsondoc.dto.UserDTO;
import com.huanmeiqi.jsondoc.form.UserForm;
import org.jsondoc.core.annotation.*;
import org.springframework.web.bind.annotation.*;

/**
 * @author cq.Wang
 * @date 2018/6/21 9:42
 * @description
 */
@RestController
@RequestMapping("/users")
@Api(name = "userController", description = "用户CRUD接口", group = "user-server")
public class UserController {
    @ApiMethod
    @RequestMapping(method = RequestMethod.GET, value = "/{userId}")
    // 注意jsondoc无法解析GetMapping、PostMapping等注解
    public @ApiResponseObject
    UserDTO getUser(@ApiPathParam(description = "用户ID") @PathVariable(name = "userId") Long userId) {
        // ...
        return new UserDTO();
    }

    @ApiMethod
    @RequestMapping(method = RequestMethod.POST)
    public @ApiResponseObject
    UserDTO addUser(@ApiBodyObject @RequestBody UserForm userForm) {
        // ...
        return new UserDTO();
    }

    @ApiMethod
    @RequestMapping(method = RequestMethod.PUT)
    public @ApiResponseObject
    UserDTO updateUser(@ApiBodyObject @RequestBody UserForm userForm) {
        // ...
        return new UserDTO();
    }

    @ApiMethod
    @RequestMapping(method = RequestMethod.DELETE, value = "/{userId}")
    public void delUser(@ApiPathParam(description = "用户ID") @PathVariable(name = "userId") Long userId) {
        // ...
    }
}

• 入参实体类和返回的DTO对象都添加jsondoc相关注解

@ApiObject(name = "userForm", description = "用户入参对象", group = "user-server")
public class UserForm {

    @ApiObjectField(description = "昵称")
    private String nickname;

    @ApiObjectField(description = "年龄")
    private Integer age;

    // ...
}

@ApiObject(name = "userDTO", description = "用户返回对象", group = "user-server")
public class UserDTO {

    @ApiObjectField(description = "用户ID")
    private Long userId;

    @ApiObjectField(description = "昵称")
    private String nickname;

    @ApiObjectField(description = "年龄")
    private Integer age;

    // ...
}

• application.properties添加配置

server.port=8088
# mandatory configuration
jsondoc.version=1.0
jsondoc.basePath=http://localhost:8088
jsondoc.packages[0]=com.huanmeiqi.jsondoc.controller
jsondoc.packages[1]=com.huanmeiqi.jsondoc.dto
jsondoc.packages[2]=com.huanmeiqi.jsondoc.form
# optional configuration
jsondoc.playgroundEnabled=true
jsondoc.displayMethodAs=URI

• 启动项目，访问http://localhost:8088/jsondoc-ui.html 并在搜索框输入http://localhost:8088/jsondoc
  

其他整合方式，譬如与mvc整合，请参考官网http://jsondoc.org/annotations.html

swagger

<dependency>
            <!--github上有许多不同版本定制了不同UI界面，我用的就不是官方的-->
            <groupId>com.battcn</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

server.port=8088
spring.swagger.title=asset service
spring.swagger.description=""
spring.swagger.version=1.0.1
spring.swagger.contact.name=cq.wang
spring.swagger.contact.email=cq.wang@shunwang.com
spring.swagger.base-package=com.yww.asset
spring.swagger.exclude-path=/actuator/**,/error

/**
 * @author cq.Wang
 * @date 2018/6/6 16:06
 * @description 接口文档 http://localhost:8088/swagger-ui.html
 */
@Api(value = "", tags = { "资产接口" }, description = "")
@RestController
@RequestMapping("/assets")
public class AssetController {
   /**
    * 根据userId查询用户的资产信息
    *
    * @param
    * @return
    */
   @ApiOperation(value = "根据userId查询用户的资产信息,注意用户必须调用该接口先初始化资产属性")
   @PostMapping("/users")
   public CommonResponse<UserAssetDTO> getUserAsset(@RequestBody UserIdForm userIdForm) {
      return null;
   }
}

public class UserIdForm extends BaseForm {
   @ApiModelProperty(required = true, value = "用户ID")
   private Long userId;
   // ...
}

入口类添加注解@EnableSwagger2Doc

相对Jsondoc而言swagger对controller层的代码入侵更少，但是实践之后发现，swagger对Long、date类型支持不够好。个人更喜欢jsondoc的UI风格