SpringBoot整合Swagger文档

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层定义的接口均展示在了接口文档中，并可以进行测试.