SpringBoot整合Swagger文档
前后端分离后,维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了。当然这是一种非常理想的状态,实际开发中却很少遇到这样的情况,接口总是在不断的变化之中,有变化就要去维护,做过的小伙伴都知道这件事有多么头大!还好,有一些工具可以减轻我们的工作量,Swagger2就是其中之一。
1.引入依赖
在工程pom.xml文件中引入依赖,springfox-swagger2 和 springfox-swagger-ui 的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.配置swagger2
写一个配置类,加上相关注解,代码如下
import org.springframework.stereotype.Component;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Component //注册容器bean
@EnableSwagger2 //开启Swagger2
public class Swagger2 {
}
3.生成文档的注解
Swagger2通过注解来生成API接口文档,文档信息包括接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档,下面是常见的注解:
- @Api:修饰整个类,用于描述Controller。
- @ApiOperation:描述类的方法,或者说一个接口。
- @ApiParam:单个参数描述。
- @ApiModel:用对象来接收参数。
- @ApiProperty:用对象接收参数时,描述一个对象的字段。
- @ApiResponse:HTTP响应的一个描述。
- @ApiResponses:HTTP响应的整体描述。
- @ApiIgnore:Swagger2忽略该api。
- @ApiError:发生错误返回的信息。
- @ApiParamImplicit:一个请求参数。
- @ApiParamsImplicit:多个请求参数。
4.改写Controller层
对Controller层涉及到的接口和方法及实体类进行改造,改造为可以生成接口文档的格式。
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import java.util.List;
@Controller
@RequestMapping("/admin")
@Api(value="用户登录controller",tags={"登陆后得用户进行操作接口"})
public class Test extends BaseController{
@ApiOperation(value="获取用户列表", notes="获取用户列表")
@RequestMapping(value = "/list", method = RequestMethod.GET)
@ApiParam
@ResponseBody
public List<TbUserLogin> queryAll(){
List<TbUserLogin> user = tbUserLoginBiz.selectAll();
System.out.println(user);
return user;
}
}
测试
启动工程,在浏览器输入 http://localhost:8080/swagger-ui.html#/ 可以看到 (我是端口是80)
在此,可以看到Controller层定义的接口均展示在了接口文档中,并可以进行测试.