Pang-Blog开发-4：spring boot整合swagger2

什么是Swagger

想要整合swagger，我们首先要知道它是什么。
下面是swagger官网的评价：
The Best APIs are Built with Swagger Tools
一目了然，swagger其实就是自动生成API文档的一个工具，有了它以后，就不用每次都手写api文档啦，哈哈哈哈哈哈。
下面我们来看看如何在spring boot里面整合swagger吧

整合swagger2

引入swagger2依赖

打开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的配置类，比如：SwaggerConfig，在配置类里面添加如下配置：

package com.pang.blog.config;

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;

/**
 * @author pang
 * @version V1.0
 * @ClassName: SwaggerConfig
 * @Package com.pang.blog.config
 * @description: swagger2配置
 * @date 2019/1/23 8:47
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pang.blog.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Pang-Blog")
                .termsOfServiceUrl("http://127.0.0.1:8877/")
                .version("1.0")
                .contact("小胖儿")
                .termsOfServiceUrl("http://localhost:8888")
                .description("Pang-Blog接口合集")
                .build();
    }
}

如上面代码所示，@Configuration注解会让spring加载这个配置，然后通过@EnableSwagger2注解启动swagger2。
然后通过createRestApi方法创建Docker的Bean以后，通过apiInfo方法标注一些可以显示的基本信息，select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，这里采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

使用swagger2

这里使用简单的demo进行演示。首先创建一个UserController类，先放代码

package com.pang.blog.controller;

import com.pang.blog.entity.RestJson;
import com.pang.blog.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author pang
 * @version V1.0
 * @ClassName: UserController
 * @Package com.pang.blog.controller
 * @description: swagger2的demo
 * @date 2019/1/26 12:42
 */
@RestController
@Api(description = "用户表", tags = "User")
public class UserController {
    @ApiOperation(value = "根据id获得User", notes = "")
    @ApiImplicitParam(name = "id", value = "用户id", dataType = "int", required = true)
    @RequestMapping(value = "/user/{id}", method = RequestMethod.GET, produces = "application/json")
    public RestJson<User> getUser(@PathVariable int id) {
        //业务代码
    }
}

这里注意几个点：
@RestController注解是spring boot构建restful api的注解
@Api(description = "用户表", tags = "User")这个注解用在类上，对类进行一些讲解说明
@ApiOperation(value = "根据id获得User", notes = "")这个注解用在方法上，可以对方法进行一些简单的描述
@ApiImplicitParam(name = "id", value = "用户id", dataType = "int", required = true)这个注解也用在方法上，可以对方法的参数进行一些讲解说明
@RequestMapping(value = "/user/{id}", method = RequestMethod.GET, produces = "application/json")这个注解是spring boot里面对API的一些设置

查看

上面的配置完成以后，我们就可以运行程序了（注意，上面有一些类是要自己创建的，比如RestJson类），运行完程序以后，我们可以放分你的地址/swagger-ui.html来查看api信息，下面是我之前的一个小项目的截图：

其他的一些配置

这里引用了大佬的博客swagger2注解详细说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性