Spring Boot 整合 Swagger

一、为什么要用 Swagger

现在的开发模式，一般都是前后端分离的，开发接口文档就显得尤为重要，前端人员需要按照后端的功能文档调用对应的接口。在没有使用 API 文档之前，很多公司都是在纸或者 MarkDown 上写文档，不仅效率低，在进行前后端交互的时候也很容易出问题。

Swagger 是一款 API 构建工具，用于满足开发人员构建 API 的需求。Swagger 使用交互式的 API 文档来改善开发人员的体验，并提供无开销的测试功能，还支持可视化的 UI 文档界面。通过 UI 文档界面，前端人员可以很清楚的知道每个接口对应的功能，后端开发人员也可以进行相应的代码测试。

二、Spring Boot 整合 Swagger

在 SpringBoot 中整合 Swagger 很简单，只需要添加对应的依赖、然后配置相关的 Bean 即可，然后使用合适的注解用于文档说明，下面我们就来这么做。

在 pom.xml 中引入对应的依赖

        <!-- 引入 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>

Swagger 配置类 SwaggerConfiguration

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jas"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger构建api文档")
                .description("swaggerTest")
                .version("1.0")
                .build();
    }
}

测试的 Controller

    @ResponseBody
    @GetMapping("/test")
    @ApiOperation(value = "swagger 测试", httpMethod = "GET", response = String.class)
    public String testSwagger(String userName) {
        return "Hello " + userName;
    }

三、访问 UI 页面文档

输入 http://{ip地址}:{端口号}/{资源路径，如果有配置}/swagger-ui.html 即可访问到 Swagger 文档页面，如下

后端开发人员可以在 API 文档上进行测试，方便问题的排查，前端人员也可以很清晰的知道每个接口对应的功能，然后就可以放心的开发啦。

四、常用的文档注解与属性

@ApiProperty：用对象接收参数时，说明属性信息

@ApiParam：描述某个参数

@Api：用于标注在 Controller 上

• description：Controller 描述信息

@ApiOperation ：对 Controller 中的资源进行定义

• value：说明信息

• httpMethod：HTTP 请求的方式

• response：返回值类型

如果请求被拦截需要添加请求不拦截

,"/swagger-ui.html"
 ,"/swagger-resources/**"

配置为@RequestBody

    @RequestMapping(value="", method=RequestMethod.POST)
    public String post(@RequestBody Book book) {
        books.put(book.getId(), book);
        return "success";
    }

在实体类中添加注解

public class Book {
    @ApiModelProperty("名字")
    private String name;
    @ApiModelProperty("价格")
    private String price;
    @ApiModelProperty("关联id")
    private Long id;

页面显示出注解