Spring Boot整合swagger

之前开发项目前后端对接，需要手写接口文档。文档更新太多时，会经常出现遗漏，这样就会出现前后端不一致的现象。而swagger的出现很好的解决了这一现象，也大大方便了开发人员，后端开发人员在测试接口方面也得到极大的效率提升。现在就介绍下springBoot整合Swagger2。

什么是Swagger

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，
对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

集成步骤

• 第一步： 在pom.xml中引入依赖

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>

上面两个依赖的作用:

springfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，
springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来

• 第二步 创建配置类
  现在Swagger2还不能为我们生成API文档,因为我们还没有对它进行配置.
  我们需要创建一个配置类,进行如下配置:

package com.study;

import com.google.common.base.Predicates;
import io.swagger.annotations.Contact;
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 Administrator on 2019/5/22.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful API")
                .description("rest api 文档构建利器")
                .termsOfServiceUrl("http://blog.csdn.net/itguangit")
                .contact("itguang")
                .version("1.0")
                .build();
    }

}

现在我们要做的配置已经能满足一个生成API文档的基本要求了,让我们启动项目,访问:http://localhost：8080/swagger-ui.html

image.png
这是Swagger-ui 为我们生成的界面.

Swagger2 注解使用

接下来我们就要好好研究下 springfox-swagger2 给我们提供的注解了.
我们新建一个Controller,用来对 User 类进行增删改查常用操作,

package com.study.controller;

import com.study.pojo.SysUser;
import com.study.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

/**
 * Created by Administrator on 2019/5/21.
 */
@Controller
@RequestMapping("/user")
@Api(description = "用户管理")
public class UserContorller {

    @Autowired
    UserService userService;

    @ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
    @RequestMapping("/userList")
    public String getUserList(ModelMap modelMap){
        List<SysUser> list = userService.getUserList();
        modelMap.addAttribute("users",list);
        return "index";
    }
}

可以看到我们在Controller上使用了 @Api(description = “用户管理”) 注解,在方法上使用了 @ApiOperation(value = “获取用户列表”, notes = “获取所有用户信息”) 注解,
这会产生什么样的效果呢? 我们可以再次访问下试试看啊:

image.png

swagger2常用的注解说明

• @Api: 描述类/接口的主要用途

• @ApiOperation: 描述方法用途

• @ApiImplicitParam: 描述方法的参数

• @ApiImplicitParams: 描述方法的参数(Multi-Params)

可以在上面 创建用户的方法上添加 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")试试看

• @ApiParam:请求属性

• @ApiIgnore: 忽略某类/方法/参数的文档

注意与 @ApiModelProperty(hidden = true)不同, @ApiIgnore 不能用在模型数据上

• @ApiResponses：响应集配置

• @ResponseHeader: 响应头设置

例如: @ResponseHeader(name=”head1”,description=”response head conf”)

好了，关于Swagger2在项目中的使用教程就到这里。