SpringBoot之集成Swagger2

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

Swagger2可以利用注解快速、自动地生成接口文档页面，在前后端分离开发中起着重要作用，方便接口测试和调用！

效果图如下：

访问URL：

http://127.0.0.1:8010/swagger-ui.htm

可以看到API根据后端Controller分类，每个API都带有注释，详细注释了参数和响应体的内容，后端设计基于RESTful风格的API（之前已经讲到），开发效率是杠杠的。

1.构建RESTful API

在使用Swagger2前我们需要有一个RESTful API的项目，SpringBoot创建RESTful API项目非常的方便和快速。

SpringBoot构建RESTful API极为简单，实际就是Spring MVC。

/**
 * <p>
 *  前端控制器
 * </p>
 *
 * @author 路飞
 * @since 2021-01-21
 */
@RestController
@RequestMapping("/goods")
public class GoodsController {

    @Autowired
    private GoodsService goodsService;

    @ApiOperation("列表显示")
    @GetMapping("/")
    public BaseResponse<List<Goods>> showGoodsList(){
        List<Goods> list = goodsService.list(null);
        return new BaseResponse<>(true,"查询成功",list);
    }

    @ApiOperation("查询商品")
    @GetMapping("/{id}")
    public BaseResponse<Goods> selGood(@PathVariable Integer id){
        Goods goods = goodsService.getById(id);
        return new BaseResponse<>(true,"查询成功",goods);
    }

    @ApiOperation("新增商品")
    @PostMapping("/")
    public BaseResponse<Integer> insGood(@RequestBody Goods goods){
        boolean save = goodsService.save(goods);
        if(save == true){
            return new BaseResponse<>(true,"添加成功",200);
        }else {
            return new BaseResponse<>(false,"添加失败",500);
        }
    }

    @ApiOperation("修改商品信息")
    @PutMapping("/{id}")
    public BaseResponse<Integer> updGood(@ModelAttribute Goods goods){
        boolean update = goodsService.updateById(goods);
        if(update == true){
            return new BaseResponse<>(true,"修改成功",200);
        }else {
            return new BaseResponse<>(false,"修改失败",500);
        }
    }

    @ApiOperation("删除商品")
    @DeleteMapping("/{id}")
    public BaseResponse<Integer> delGood(@PathVariable Integer id){
        boolean delete = goodsService.removeById(id);
        if(delete == true){
            return new BaseResponse<>(true,"修改成功",200);
        }else {
            return new BaseResponse<>(false,"修改失败",500);
        }
    }

}

接下来，详细讲下Swgger2环境的搭建和常用注解功能

2.项目依赖

maven依赖：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!--swagger-->
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>
    <!--MySQL JDBC驱动-->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!--Druid-->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid</artifactId>
        <version>1.1.1</version>
    </dependency>
    <!--mybatis-plus-->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.0.5</version>
    </dependency>
    <dependency>
        <groupId>org.apache.velocity</groupId>
        <artifactId>velocity-engine-core</artifactId>
        <version>2.0</version>
    </dependency>
</dependencies>

这里分享个自己踩过的坑:

查阅官网，可以看到Swagger2依赖并没有这么多，但我在一次使用RESTful 开发API，利用Swagger生成接口文档时，发生报错：

1	java.lang.NumberFormatException: For input string: ""

只要浏览器中一访问Swagger接口文档，就会发生这个报错，可以看到就是空字符串无法自动转换成数字类型造成的，原因很简单，请求Swagger的页面就发送了空的字符串参数，但{id}需要int，故发生报错。

分析和解决：

io.springfox:springfox-swagger2:2.9.2中依赖了swagger-models的1.5.20版本，我们可以排除springfox-swagger2中的swagger-models依赖，导入io.swagger:swagger-models的1.5.21版本即可。

故映入依赖：

 <!--swagger-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>

其次，引入MybatiesPlus简化操作，创建和配置好数据库，启动DevGenerator.java，自动生成后端基础环境。

3.编写Swagger配置类

@Configuration
@EnableSwagger2
/**
 * Swagger配置
 * @author 路飞
 * @create 2021/1/5
 */
public class SwaggerConfig {
    /**
     * 是否启用swagger文档
     */
    @Value("${swagger.enable}")
    private boolean enable;

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .build();
    }

    //配置swagger 信息 = apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("接口文档", "https://github.com/luffy997", "389783961@qq.com");

        return new ApiInfo("接口文档",
                "接口文档",
                "v1.0",
                "www.baidu.com", contact,
                "Appache2.0",
                "http://www.appache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

Swagger2提供了一些注解来丰富接口的信息,常用的有:

说明：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- paramType：参数放在哪个地方
  - header–>请求参数的获取：@RequestHeader
  - query–>请求参数的获取：@RequestParam
  - path（用于restful接口）–>请求参数的获取：@PathVariable
  - body（不常用）
  - form（不常用）
- name：参数名
- dataType：参数类型
- required：参数是否必须传
- value：参数的意思
- defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如”请求参数没填好”
- response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性