SpringBoot整合Swagger2

手写Api文档的几个痛点：

1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2. 接口返回结果不明确
3. 不能直接在线测试接口，通常需要使用工具，比如postman
4. 接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

一、依赖

	io.springfox
	springfox-swagger2
	2.9.2



	io.springfox
	springfox-swagger-ui
	2.9.2

 

二、Swagger配置类

package com.ws.soon.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @desc 自动生成接口文档
 * @url http://localhost:8023/swagger-ui.html
 * @author wangsaisoon
 * @date 2020年1月2日 下午1:54:41
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.ws.soon.controller"))
                .paths(PathSelectors.any())
                .build();
//        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                // 创建人
                .contact(new Contact("Bryan", "http://www.wangsaisoon.com/", ""))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述")
                .build();
    }
}

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

package com.ws.soon;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
@MapperScan("com.ws.soon.mapper")
public class App 
{
    public static void main( String[] args )
    {
        SpringApplication.run(App.class, args);
    }
}

三、Restful 接口

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

package com.ws.soon.controller;

import java.util.List;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.BeanUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import com.ws.soon.base.BaseController;
import com.ws.soon.base.DataRow;
import com.ws.soon.base.ResultVO;
import com.ws.soon.controller.dto.UserInfoDTO;
import com.ws.soon.entity.UserInfo;
import com.ws.soon.service.UserInfoService;

import lombok.extern.slf4j.Slf4j;

/**
 * @author wangsaisoon
 * @desc 用户信息
 * @date 2019年12月6日 上午8:36:09
 */
@Slf4j
@Api(value = "用户基本信息接口")
@RequestMapping("/user/info")
@RestController
public class UserInfoController extends BaseController {

    @Autowired
    private UserInfoService userInfoService;

    @ApiOperation(value = "保存用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "eMail", value = "邮箱", required = true, dataType = "String"),
            @ApiImplicitParam(name = "remarks", value = "备注", required = true, dataType = "String")
    })
    // @ApiImplicitParam(name = "dto", value = "用户对象", dataType = "com.ws.soon.controller.dto.UserInfoDTO")
    @PostMapping
    public ResultVO save(UserInfoDTO dto) {
        log.info("dto={}", dto);
        UserInfo userInfo = new UserInfo();
        BeanUtils.copyProperties(dto, userInfo);
        log.info("userInfo={}", userInfo);

        int result = userInfoService.save(userInfo);

        if (result == 1) {
            return ResultVO.success();
        }
        return ResultVO.error();
    }

    @ApiOperation(value = "查询所有")
    @GetMapping
    public ResultVO findAll() {
        List list = userInfoService.findAll();
        log.info("list={}", list);

        // 出参
        ResultVO resultVO = new ResultVO();
        resultVO.setResult(list);
        return resultVO;
    }

    @ApiOperation(value = "通过id查询")
    @GetMapping("/{userId}")
    public ResultVO findById(@PathVariable(value = "userId", required = true) Integer userId) {
        log.info("userId={}", userId);
        UserInfo userInfo = userInfoService.findById(userId);
        log.info("userInfo={}", userInfo);

        // 出参
        ResultVO resultVO = new ResultVO();
        DataRow dataRow = this.getDataRow();
        dataRow.set("user_id", userInfo.getUserId());
        dataRow.set("user_name", userInfo.getUserName());
        dataRow.set("e_mail", userInfo.getEMail());
        dataRow.set("remarks", userInfo.getRemarks());
//		resultVO.setResult(userInfo);
        resultVO.setResult(dataRow);
        return resultVO;
    }

    /*@ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户id", required = true, dataType = "Integer"),
            @ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "eMail", value = "邮箱", required = true, dataType = "String"),
            @ApiImplicitParam(name = "remarks", value = "备注", required = true, dataType = "String")
    })*/
    @ApiOperation(value = "修改", notes="通过id更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户id", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "dto", value = "用户对象", required = true, dataType = "UserInfo")
    })
    @PutMapping("/{userId}")
    public ResultVO updateById(@PathVariable(value = "userId", required = true) Integer userId, UserInfo dto) {
        log.info("dto={}", dto);
        UserInfo userInfo = new UserInfo();
        BeanUtils.copyProperties(dto, userInfo);
        log.info("userInfo={}", userInfo);

        int result = userInfoService.updateById(userInfo);

        if (result == 1) {
            return ResultVO.success();
        }
        return ResultVO.error();
    }

    @ApiOperation(value = "通过id删除")
    @DeleteMapping("/{userId}")
    public ResultVO deleteById(@PathVariable(value = "userId", required = true) Integer userId) {
        log.info("userId={}", userId);

        int result = userInfoService.deleteById(userId);

        if (result == 1) {
            return ResultVO.success();
        }
        return ResultVO.error();
    }


}

四、Swagger2文档

启动SpringBoot项目，访问 http://localhost:8023/swagger-ui.html