前后端分离之Swagger2

1. 问题描述

随着软件过程的不断发展，前后端分离开发模式被越来越的开发团队使用，今天介绍下前后分离中必用的接口设计与调试工具-swagger2，前端人员根据swagger的描述，进行参数的传递；前后端联调的时候，出现问题，首先使用swagger进行测试调用，定位问题，还可以通过界面导出swagger2接口文档，修改完善后作为其他系统调用说明文档。

2. 问题方案

采用springboo+swagger2方式运行swagger。

2.1 pom文件配置

        <!--swagger-->
        <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>

2.2 springboot启动类配置标签

@EnableSwagger2             //启动swagger注解
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

2.3 java代码及swagger界面说明

2.3.1 java代码（针对实际项目做了下处理）

@Api(description = "测试管理类")
public class TestController {

 @RequestMapping(value = "/getTestByUid", method = RequestMethod.GET)
    @ApiOperation(value = "查询接口,获取当前用户数据", response = Object.class)
    public Object getTestByUid(@ApiParam(value = "类型，1公开，2新建，3收藏4，分享") @RequestParam String type) {
        try {
            Object result = testService.getTestByUid(type);
            return new ResponseEntity(result, HttpStatus.OK);
        } catch (Exception e) {
            logger.error("查询接口报错", e);
            return new ResponseEntity(e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
    }

2.3.2 swagger效果图

2.3.3 swagger界面说明

一般使用这几个标签就够用了，详细API说明可以百度一下，就不一一说明了。

（1） @Api(description = "测试管理类")

​ 该标签用于类上，是对整个类的说明，例如：用户管理模块，会在swagger2界面上生成一个一级菜单，方法是它的二级菜单。

（2） @ApiOperation(value = "查询接口,获取当前用户数据", response = Object.class)

该标签用于方法上，Value是描述，还可以定义nodes进行进一步说明。

（3）@ApiParam(value = "类型，1公开，2新建，3收藏4，分享")

改标签用于定义参数描述。

三个标签分别是类->方法->参数

另外：点击 ”Try it out“按钮就可以调用后台服务，进行前后端联调测试及问题定位。

---