前后端分离之Swagger2

时间:2022-09-14 17:09:41

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效果图

前后端分离之Swagger2

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“按钮就可以调用后台服务,进行前后端联调测试及问题定位。