浅谈 Swagger

前言

在平时的开发过程中，都会进行前后端的联调，如果后端Api接口写好了之后直接与前端页面进调试的话，效果会更好，但是为了提高效率，一般会通过一些测试工具提前来测试功能是否实现，比如postman、jmeter、loadrunner等，下面介绍一种用起来比以上工具更方便的工具Swagger。Swagger是一种通用的、和编程语言无关的API的描述规范，它是一个很好的对前后端分离项目进行对接的工具，通过swagger，后端开发人员可以很好的对自己写的API接口进行测试，前端开发人员更方便的了解接口的类型，以及接口的url，并且清楚后端需要的参数值等等，大大提高项目的开发效率。

基于springBoot使用Swagger

1、在pom.xml文件中引入依赖

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

第一个依赖引入swagger的api，第二个依赖是对swagger访问界面进行ui美化

2、添加Swagger配置类

一般为了规范，在项目路径下建一个放置配置类文件的config包，然后在此包下面写Swagger配置文件，内容如下：

//说明该类为配置类，即把该类作为spring的xml配置文件中的bean
@Configuration
//启动swagger
@EnableSwagger2
//自动扫描，该注解会扫描指定路径下的所有的配置，默认扫描该类所在包下面的所有配置文件
@ComponentScan("com.hand.springboot")
public class SwaggerApiConfig {

    /*
     * 创建API应用
     * apiInfo() 增加API相关信息
     * select() 选择哪些路径和api会生成document
     * apis() 对所有api进行监控
     * paths() 对所有路径进行监控
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hand.springboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /*
     * 创建该API的基本信息
     * title:访问界面的标题
     * description：描述
     * version：版本号
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("欢迎使用Swagger测试")
                .description("基于SpringBoot实现简单的学生信息的处理")
                .version("1.0")
                .license("version1.0")
                .build();
    }
}

一般经过上面两步操作，swagger就配置好了，下面就是写api接口的事情了，写好之后通过url进行访问

3、controller控制层使用

@RestController
@RequestMapping("/student")
public class StudentController {

    @Autowired
    private  IStudentService studentService;

    /**
     * 学生信息添加
     * @param code 学生编号
     * @param name 学会姓名
     * @return
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "code", value = "学生编号", paramType = "query"),
            @ApiImplicitParam(name = "name", value = "学会姓名", paramType = "query")
    })
    @ApiOperation(value = "添加")
    @PostMapping("/add")
    private String addStudent(@RequestParam(required = false) String code, @RequestParam(required = false) String name) {
        studentService.addStu(code,name);
        return "add success";
    }
}

4、Swagger ui界面访问

本地启动项目访问地址：http://127.0.0.1:8080/swagger-ui.html
界面如下：

image.png
新增接口测试：
image.png
一般开发过程中为了开发和测试的方便，需要合理使用一些注解来提高效率，注解的使用请查看：https://www.jianshu.com/p/296d77fac00d