java自动生成接口文档

  • maven依赖
  • 工具类
  • 展示效果
  • 首页
  • 接口页



在平时的开发过程中必定要写接口文档 作为程序员 最烦的2件事


1、别人让你写接口文档


2、接手别人的项目没有接口文档


由此可见 接口文档确实是一件很繁琐乏味却又必不可少的工作，那么我们可否通过程序自动生成接口文档省去这一繁琐的过程呢？


话不多说 上代码！

maven依赖

要使用javamail的jar包首先需要导入依赖

<!--Swagger-UI API文档生产工具-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>
<!--整合Knife4j-->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.4</version>
</dependency>

这里我们整合了swagger2和swagger-ui
swagger-ui是在swagger2的基础上对页面的展示效果进行一定的优化

工具类

Swagger2API文档的配置

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("huafu.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("华富项目演示")
                .description("huafu")
                .version("1.0")
                .build();
    }
}

这个是接口返回的工具类

import io.swagger.annotations.ApiModelProperty;

/**
 * 通用返回对象
 * Created by macro on 2019/4/19.
 */
public class CommonResult<T> {

    @ApiModelProperty(value = "返回代码")
    private String code;
    @ApiModelProperty(value = "返回信息")
    private String message;
    @ApiModelProperty(value = "返回数据")
    private T data;

    protected CommonResult() {
    }

    protected CommonResult(String code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    /**
     * 成功返回结果
     *
     * @param data 获取的数据
     */
    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<T>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }

    /**
     * 成功返回结果
     *
     * @param data 获取的数据
     * @param  message 提示信息
     *
     */
    public static <T> CommonResult<T> success(T data, String message) {
        return new CommonResult<T>(ResultCode.SUCCESS.getCode(), message, data);
    }

    /**
     * 失败返回结果
     * @param errorCode 错误码
     */
    public static <T> CommonResult<T> failed(IErrorCode errorCode) {
        return new CommonResult<T>(errorCode.getCode(), errorCode.getMessage(), null);
    }

    /**
     * 失败返回结果
     * @param message 提示信息
     */
    public static <T> CommonResult<T> failed(String message) {
        return new CommonResult<T>(ResultCode.FAILED.getCode(), message, null);
    }

    /**
     * 失败返回结果
     */
    public static <T> CommonResult<T> failed() {
        return failed(ResultCode.FAILED);
    }

    /**
     * 参数验证失败返回结果
     */
    public static <T> CommonResult<T> validateFailed() {
        return failed(ResultCode.VALIDATE_FAILED);
    }

    /**
     * 参数验证失败返回结果
     * @param message 提示信息
     */
    public static <T> CommonResult<T> validateFailed(String message) {
        return new CommonResult<T>(ResultCode.VALIDATE_FAILED.getCode(), message, null);
    }

    /**
     * 未登录返回结果
     */
    public static <T> CommonResult<T> unauthorized(T data) {
        return new CommonResult<T>(ResultCode.UNAUTHORIZED.getCode(), ResultCode.UNAUTHORIZED.getMessage(), data);
    }

    /**
     * 未授权返回结果
     */
    public static <T> CommonResult<T> forbidden(T data) {
        return new CommonResult<T>(ResultCode.FORBIDDEN.getCode(), ResultCode.FORBIDDEN.getMessage(), data);
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

这里可以根据自己的实际需求自定义返回内容

/**
 * 枚举了一些常用API操作码
 * Created by macro on 2019/4/19.
 */
public enum ResultCode implements IErrorCode {
    SUCCESS("0", "成功"),
    FAILED("500", "失败！"),
    VALIDATE_FAILED("404", "参数检验失败"),
    UNAUTHORIZED("401", "暂未登录或token已经过期"),
    FORBIDDEN("403", "没有相关权限");
    private String code;
    private String message;

    private ResultCode(String code, String message) {
        this.code = code;
        this.message = message;
    }

    public String getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}
/**
 * 封装API的错误码
 * Created by macro on 2019/4/19.
 */
public interface IErrorCode {
    String getCode();

    String getMessage();
}

实体类 每个字段上面需要添加@ApiModelProperty对字段进行结束说明

import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

public class User implements Serializable {
    @ApiModelProperty(value = "主键")
    private Integer id;

    @ApiModelProperty(value = "用户名 邮箱地址")
    private String userName;

    @ApiModelProperty(value = "登陆密码 md5加密")
    private String password;

    @ApiModelProperty(value = "邮箱地址")
    private String email;

    @ApiModelProperty(value = "matrixId")
    private Integer matrixId;

    @ApiModelProperty(value = "是否从matrix跳转 1:是 0:否")
    private Integer isMatrix;

    @ApiModelProperty(value = "用户状态  1:正常  0:注销")
    private Integer status;

    private static final long serialVersionUID = 1L;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName == null ? null : userName.trim();
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password == null ? null : password.trim();
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email == null ? null : email.trim();
    }

    public Integer getMatrixId() {
        return matrixId;
    }

    public void setMatrixId(Integer matrixId) {
        this.matrixId = matrixId;
    }

    public Integer getIsMatrix() {
        return isMatrix;
    }

    public void setIsMatrix(Integer isMatrix) {
        this.isMatrix = isMatrix;
    }

    public Integer getStatus() {
        return status;
    }

    public void setStatus(Integer status) {
        this.status = status;
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append(getClass().getSimpleName());
        sb.append(" [");
        sb.append("Hash = ").append(hashCode());
        sb.append(", id=").append(id);
        sb.append(", userName=").append(userName);
        sb.append(", password=").append(password);
        sb.append(", email=").append(email);
        sb.append(", matrixId=").append(matrixId);
        sb.append(", isMatrix=").append(isMatrix);
        sb.append(", status=").append(status);
        sb.append(", serialVersionUID=").append(serialVersionUID);
        sb.append("]");
        return sb.toString();
    }
}

接下来的controller的配置

//接口文档地址：http://localhost:8090/swagger-ui.html   http://127.0.0.1:8090/doc.html
//自动生成 执行Generator中的main方法
@Api(tags = "TestController", description = "商品品牌管理")
@Controller
@RequestMapping("/test")
public class TestController {

    private static Logger logger = LoggerFactory.getLogger(TestController.class);

    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required=false, dataType = "Integer", paramType = "query")
    })
    @ApiOperation("测试普通请求方式")
    @RequestMapping(value = "listAll", method = RequestMethod.GET)
    @ResponseBody
    public CommonResult<User> get(@RequestParam(value = "id", required = false) Integer id) {
        User user = new User();
        user.setId(1);
        user.setEmail("xxxxxxx@qq.com");
        user.setMatrixId(2);
        user.setPassword("password");
        user.setStatus(1);
        user.setUserName("xxxx");
        return CommonResult.success(user);
    }

    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用户ID", required=false, dataType = "User", paramType = "body")
    })
    @ApiOperation("测试json请求方式")
    @RequestMapping(value = "madan", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult<User> post(@RequestBody User user, HttpServletRequest request, HttpServletResponse response) {

        logger.info(" 获取到的参数 param:{}", user);
        return CommonResult.success(user);
    }

}

以上代码即完成了所有自动接口文档的开发 接下来我们看看效果

展示效果

自动接口文档的访问网址有2个 一个是默认页面 一个是UI优化后的页面
我这里项目的启动端口为8090 可以根据自己项目的端口修改访问地址
默认页面：http://localhost:8090/swagger-ui.html
UI优化后页面：http://127.0.0.1:8090/doc.html

首页

java pageObject 接口自动化 java自动化接口文档_返回结果

该页面为默认页 页面中红框圈住1、2、3部分为Swagger2Config中设置

页面中红框圈住4部分为Controller中设置

java pageObject 接口自动化 java自动化接口文档_接口文档_02


java pageObject 接口自动化 java自动化接口文档_spring_03

接口页

接口文档页面展示 具体的展示内容为上面Controller中配置

java pageObject 接口自动化 java自动化接口文档_接口文档_04

自动生成的接口文档附带自动调用功能调试页面

java pageObject 接口自动化 java自动化接口文档_接口文档_05