在平时的开发过程中必定要写接口文档 作为程序员 最烦的2件事
1、别人让你写接口文档
2、接手别人的项目没有接口文档
由此可见 接口文档确实是一件很繁琐乏味却又必不可少的工作，那么我们可否通过程序自动生成接口文档省去这一繁琐的过程呢？
话不多说 上代码！
要使用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中配置
自动生成的接口文档附带自动调用功能调试页面
服务热线