脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → java → java自动生成接口文档

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

 更新时间：2024年10月11日 11:24:14   作者：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自动生成接口文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • Java人民币小写转大写字符串的实现

    Java人民币小写转大写字符串的实现

    这篇文章主要介绍了Java人民币小写转大写字符串的实现，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2021-04-04
  • java实现实时通信聊天程序

    java实现实时通信聊天程序

    这篇文章主要为大家详细介绍了java实现实时通信聊天程序，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
    2022-06-06
  • Mybatis查不到数据查询返回Null问题

    Mybatis查不到数据查询返回Null问题

    mybatis突然查不到数据，查询返回的都是Null，但是 select count(*) from xxx查询数量，返回却是正常的。好多朋友遇到这样的问题不知所措，下面小编通过本教程简单给大家说明下
    2016-08-08
  • 深入理解Spring Aop的执行顺序

    深入理解Spring Aop的执行顺序

    本文将结合实例代码，介绍Spring Aop的执行顺序，非常具有实用价值，需要的朋友可以参考下
    2021-06-06
  • Spring的连接数据库以及JDBC模板(实例讲解)

    Spring的连接数据库以及JDBC模板(实例讲解)

    下面小编就为大家带来一篇Spring的连接数据库以及JDBC模板(实例讲解)。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
    2017-10-10
  • SpringBoot @value注解动态刷新问题小结

    SpringBoot @value注解动态刷新问题小结

    @Value注解 所对应的数据源来自项目的 Environment 中,我们可以将数据库或其他文件中的数据,加载到项目的 Environment 中,然后 @Value注解 就可以动态获取到配置信息了,这篇文章主要介绍了SpringBoot @value注解动态刷新,需要的朋友可以参考下
    2023-09-09
  • SpringBoot如何优雅的处理全局异常

    SpringBoot如何优雅的处理全局异常

    这篇文章主要给大家介绍了关于SpringBoot如何优雅的处理全局异常的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用SpringBoot具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧
    2019-05-05
  • Idea插件安装和管理方式

    Idea插件安装和管理方式

    这篇文章主要介绍了Idea插件安装和管理方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-08-08
  • Java解析http协议字符串的方法实现

    Java解析http协议字符串的方法实现

    本文主要介绍了Java解析http协议字符串的方法实现，我们探讨了如何使用Java解析HTTP协议字符串，并将其封装成了一个HttpRequest类，具有一定的参考价值，感兴趣的可以了解一下
    2023-09-09
  • 一篇文章带你入门Java基本概念

    一篇文章带你入门Java基本概念

    本文主要介绍了Java编程的基本概念基本概念，可以帮助我们更加深刻的所要讲解的Java命令，具有很好的参考价值。下面跟着小编一起来看下吧，希望能给你带来帮助
    2021-08-08

最新评论