Spring Boot集成SpringFox 3：生成Swagger接口文档

关注程序员的故事，一块儿用技术改变世界html

SpringFox介绍java

SpringFox 是一个开源的API Doc的框架，它的前身是swagger-springmvc，能够将咱们的Controller中的方法以文档的形式展示。官方定义为： Automated JSON API documentation for API's built with Spring。

Swagger介绍程序员

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，容许API来始终保持同步。web

SpringFox使用教程

第一步： Maven框架机构Springboot项目，依赖SpringFox包：

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version></dependency>

第二步： 在Springboot项目启动添加注解@EnableOpenApi:

package com.missye.swagger;
import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.oas.annotations.EnableOpenApi;
@EnableOpenApi@SpringBootApplicationpublic class SwaggerApplication {
 public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class, args); }
}

第三步 ：建立测试API接口，包含实体类/控制器

用户实体类：

package com.missye.swagger;
import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;
/** * 用户实体类信息 * @author missye * @since 2020/07/21 */@Data@NoArgsConstructor@AllArgsConstructor@ApiModel("用户基本信息")public class SysUser {
 /** * 用户名 */ @ApiModelProperty("用户名") private String userName; /** * 用户昵称 */ @ApiModelProperty("用户昵称") private String nickName; /** * 邮件 */ @ApiModelProperty("邮件") private String email; /** * 手机号 */ @ApiModelProperty("手机号") private String mobile;
}

用户控制器：spring

package com.missye.swagger;
import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;import java.util.List;
/** * 用户控制器 * @author missye * @since 2020/07/21 */@Api(tags = "用户管理控制器")@RestController@RequestMapping("/sysUser")public class SysUserController {
 /** * 保存用户信息 * @param sysUser * @return ResultT<java.lang.String> * @author missye * @since 2020/7/21 */ @ApiOperation("保存用户信息") @PostMapping("/saveSysUser") public ResultT<String> saveSysUser(@RequestBody SysUser sysUser) { //保存用户信息
 return ResultT.ok("用户保存成功！"); }
 /** * 获取用户信息 * @param sysUser * @return ResultT<com.missye.swagger.SysUser> * @author missye * @since 2020/7/21 */ @ApiOperation("获取用户信息") @PostMapping("/getSysUser") public ResultT<SysUser> getSysUser(@RequestBody SysUser sysUser) { return ResultT.ok(new SysUser()); }
 /** * 获取全部用户信息 * @param * @return ResultT<java.util.List < com.missye.swagger.SysUser>> * @author missye * @since 2020/7/21 */ @ApiOperation("获取全部用户信息") @PostMapping("/getAllSysUser") public ResultT<List<SysUser>> getAllSysUser() { return ResultT.ok(new ArrayList<SysUser>()); }
}

API统一响应工具类：springboot

package com.missye.swagger;
import lombok.Data;
import java.io.Serializable;import java.util.List;
/** * Api响应结果信息 * @author missye * @program springboot-company * @since 2020-05-16 09:42 **/public class ResultT<T> implements Serializable {
 private static final long serialVersionUID = 9142315231410107803L;
 /** * 成功状态 * @ignore */ private static final Integer SUCCESS = 0; /** * 成功状态 * @ignore */ private static final String MSG_SUCCESS = "业务处理成功"; /** * 失败状态码 * @ignore */ private static final Integer FAIL = -1; /** * 失败状态码 * @ignore */ private static final String MSG_FAIL = "业务处理失败"; /** * 业务错误码 */ private Integer code; /** * 描述 */ private String msg; /** * 结果集 */ private T content;
 /** * 业务处理成功，但无业务数据 */ public ResultT() { this(SUCCESS, MSG_SUCCESS, null); }
 /** * 业务处理成功，但有业务数据 * @param content 结果数据 */ public ResultT(T content) { this(SUCCESS, MSG_SUCCESS, content); }
 /** * 默认处理时自定义业务编码，没有业务数据 * @param code 错误编码 * @param msg 提示消息 */ public ResultT(int code, String msg) { this(code, msg, null); }
 /** * 默认处理时，自定义业务编码消息和业务数据 * @param code 错误编码 * @param msg 提示消息 */ public ResultT(int code, String msg, T content) { this.setCode(code); this.setMsg(msg); this.setContent(content); }
 /** * 自定义返回错误的消息，无业务数据 * @param code 错误编码 * @param msg 错误消息 * @return 错误结果 */ public static <T> ResultT<T> error(int code, String msg) { return new ResultT<>(code, msg, null); }
 /** * 返回默认错误. 有业务数据 * @param msg 错误消息(业务错误) * @return 错误结果 */ public static ResultT<String> error(String msg) { return new ResultT<>(FAIL, msg, null); }
 /** * 返回默认错误，无业务数据 * @return 错误结果 */ public static <T> ResultT<T> error() { return error(FAIL, MSG_FAIL); }
 /** * 返回自定义成功的消息，无业务数据 * @param code 自定义成功编码 * @param msg 正确消息 * @return 正确结果 */ public static <T> ResultT<T> ok(Integer code, String msg) { return new ResultT<T>(code, msg); }
 /** * 成功默认成功状态，有业务数据 * @param content 业务数据能够是List、Entity等数据 * @return 正确结果 */ public static <T> ResultT<T> ok(T content) { return new ResultT<>(content); }
 /** * 返回默认成功的状态信息，无业务数据 * @return 正确结果 */ public static <T> ResultT<T> ok() { return new ResultT<>(); }
 /** * 根据业务条件返回成功或失败的结果,必须保证成功和失败返回的类型是一致的 * @param checked 检查条件 * @param sucess 条件为true时成功返回的消息 * @param fail 条件为false的失败返回的消息 * @return 返回结果 */ public static ResultT<String> on(boolean checked, String sucess, String fail) { return checked ? ResultT.ok(SUCCESS, sucess) : ResultT.error(FAIL, fail); }
 /** * 获取结果编码 * @return 结果编码 * @author zengxueqi */ public Integer getCode() { return code; }
 /** * 设置结果编码 * @param code 结果编码 * @return * @author missye */ public ResultT<T> setCode(Integer code) { this.code = code; return this; }
 /** * 获取消息提示 * @return 消息提示 * @author missye */ public String getMsg() { return msg; }
 /** * 设置消息提示 * @param msg 消息提示 * @return 对象 * @author missye */ public ResultT<T> setMsg(String msg) { this.msg = msg; return this; }
 /** * 获取业务数据 * @return 业务数据 * @author zengxueqi */ public T getContent() { return content; }
 /** * 设置业务数据 * @param content 业务数据 * @return 结果数据 * @author missye */ public ResultT<T> setContent(T content) { this.content = content; return this; }}

第四步： 启动Springboot项目，访问Swagger页面：http://localhost:8080/swagger-ui/index.html

打开其中一个API接口文档，能够包含接口的请求与响应的详细信息，而且支持在线接口测试。

注解说明
服务器

本文测试案例总共用到4个SpringFox注解，以下：

@Api：用在类上，说明该类的做用。能够标记一个Controller类作为swagger 文档资源。
@ApiOperation：用在方法上，说明方法的做用，每个url资源的定义。
@ApiModel：描述一个Model的信息。
@ApiModelProperty：描述一个model的属性。

以上就是Springboot集成SpringFox生成Swagger接口文档的详细教程，虽然Swagger存在代码入侵性，可是在Api接口测试方面，它仍是很是的不错，目前还多大公司使用改插件，可见其便捷性了。

本文分享自微信公众号 - 程序猿的故事（zengxueqi-music）。
若有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一块儿分享。微信