java

关注公众号 jb51net

关闭
首页 > 软件编程 > java > java自动生成接口文档

java自动生成接口文档完整代码示例

作者：Diamond0810

在软件开发中,编写接口文档是一项必要但繁琐的任务,为了简化这一过程,可以通过使用Swagger2和Swagger-UI来自动生成接口文档,这篇文章主要介绍了java自动生成接口文档的相关资料,需要的朋友可以参考下

在平时的开发过程中必定要写接口文档 作为程序员 最烦的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

首页

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

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

接口页

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

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

总结 

到此这篇关于java自动生成接口文档的文章就介绍到这了,更多相关java自动生成接口文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:
阅读全文