本文主要讲解springboot是如何通过整合Swagger-UI来实现一份相当完善的在线API文档的。
1. Swagger简介
Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。
常用注解
- @Api：用于修饰Controller类，生成Controller相关文档信息
- @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
- @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
- @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息
2.整合Swagger-UI
2.1 添加项目依赖
在pom.xml文件中加入Swagger-UI相关依赖
<!-- Swagger UI -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2.2 添加Swagger-UI的配置
添加Swagger配置类Swagger2Config
package com.mzm.springboot.config;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Value("${swagger.title}")
private String title;
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.mzm.springboot.controller")) //为当前包下controller生成API文档
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //为有@Api注解的Controller生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //为有@ApiOperation注解的方法生成API文档
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().
title("测试Swagger2")
.description("Spring Boot中使用Swagger2构建RESTful APIs")
.version("1.0.0")
.contact(new Contact("mzm", "https://gitee.com/moses_mao", "297531644@qq.com"))
.build();
}
}
Swagger对生成API文档的范围有三种不同的选择
- 生成指定包下面的类的API文档
- 生成有指定注解的类的API文档
- 生成有指定注解的方法的API文档
2.3 controller加入注解
package com.mzm.springboot.controller;
import com.mzm.springboot.controller.common.BaseController;
import com.mzm.springboot.exception.BusinessException;
import com.mzm.springboot.exception.EmBusinessError;
import com.mzm.springboot.response.CommonReturnType;
import com.mzm.springboot.service.UserSevice;
import com.mzm.springboot.service.model.UserModel;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "HomeController", description = "后台首页管理")
@RestController("user")
@RequestMapping("/user")
public class HomeController extends BaseController {
@Autowired
private UserSevice userSevice;
@ApiOperation("hello word")
@RequestMapping(value = "/hello", method = RequestMethod.GET)
public String hello() {
return "hello world";
}
@ApiOperation("获取单个用户")
@RequestMapping(value = "/get", method = RequestMethod.GET)
public CommonReturnType getUser(@RequestParam(name = "id") Integer id) throws BusinessException {
UserModel userModel = userSevice.getUserById(id);
if (userModel == null) {
throw new BusinessException(EmBusinessError.USER_NOT_EXISTS);
}
return CommonReturnType.create(userModel);
}
}