springBoot集成swagger2

前言

作为一个后台开发人员，写接口文档和接口测试无疑是最令人痛心疾首的事情了，随着业务的繁复，接口文档的维护变得更加困难了，因此，在本章将学习swagger2，有了它以后接口测试将变得更加的方便，最重要的是无需手动维护接口文档了，和前端工程师的合作将变得更加灵活。

springBoot集成swagger2

添加maven依赖

<!--引入swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>LATEST</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>LATEST</version>
</dependency>

swagger2配置

package com.baozoumouse.swagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by admin on 2019/3/5.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.baozoumouse.controller")) //自动扫描路径
                        .paths(PathSelectors.any())
                        .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                        .title("Spring Boot中使用Swagger2构建Restful APIs")
                        .description("tianmlin测试swagger2")
                        .termsOfServiceUrl("https://github.com/tianmlin19/")
                        .version("1.0")
                        .build();
    }


}

controller配置

package com.baozoumouse.controller;

import com.baozoumouse.domain.Student;
import com.baozoumouse.service.FirstService;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import java.util.stream.Collectors;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * Created by admin on 2019/2/11.
 */

@RestController
@RequestMapping(value = "/tml")
public class FirstController {

    @Autowired
    private FirstService firstService;

    private static Logger logger = LoggerFactory.getLogger(FirstController.class);

    private static final Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd HH:mm:ss").disableHtmlEscaping()
                    .create();


    @RequestMapping(value = "/findByName", method = {RequestMethod.POST, RequestMethod.GET})
    @ApiOperation(value = "根据学生姓名查询学生详细信息")
    @ApiImplicitParam(name = "userName", value = "学生的用户名", required = true, dataType = "String")
    public Student hello(String userName) {

        logger.info("hello==>enter");
        long count = firstService.listAllStudent().stream().filter(student -> student.name.equals(userName)).count();
        if (count == 1) {
            return firstService.listAllStudent().stream().filter(student -> student.name.equals(userName))
                            .findFirst().get();
        } else {
            return null;
        }

    }

    @RequestMapping(value = "/findMatchedResult", method = {RequestMethod.POST, RequestMethod.GET})
    @ApiOperation(value = "查询大于一定score分数的前size名学生用户")
    @ApiImplicitParams({
                    @ApiImplicitParam(name = "score", value = "分数", required = true, dataType = "int"),
                    @ApiImplicitParam(name = "size", value = "用户数量限制", required = true, dataType = "int")
    })
    public List<Student> listStudents(@RequestParam(required = true) Integer score,
                    @RequestParam(required = true) Integer size) {
        logger.info("listStudents==>enter");

        List<Student> collect = firstService.listAllStudent().stream()
                        .filter(student -> student.score > Integer.valueOf(score)).limit(size)
                        .collect(
                                        Collectors.toList());
        logger.info("collect:{}", gson.toJson(collect));
        return collect;
    }

}

接口测试

• 启动springboot项目，controller和swagger2的配置类都必须和springboot的启动类在同一个包下，因为@SpringBootApplication注解默认扫描的就是：该注解所在类的包下的所有bean；
• 项目启动成功后，访问http://localhost:8080/swagger-ui.html#，即可访问swagger2的UI界面；
• 查看接口详情，如下：

• 接口测试，常见的接口测试可以使用postman或者fiddler来完成，但是相比而言，swagger2的ui接口测试还是略胜一筹，如下：

 

 总结

在springboot中集成swagger2后，接口文档和接口测试将变得更加的简洁，更全的代码请移步我的github：https://github.com/tianmlin19/，谢谢！