SpringBoot整合Swagger2

一、序言：

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

二、springboot整合swagger2

1、依赖：

       
            io.springfox
            springfox-swagger-ui
            2.6.1
        
        
            io.springfox
            springfox-swagger2
            2.6.1
        

2、Swagger配置类

package com.left;

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.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 
 *     @author : orange
 *     e-mail : [email protected]
 *     time   : 2018/8/27 14:49
 *     desc   : swagger配置
 *     version: 1.0
 * 
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket restApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.left.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("springboot整合swagger2")
                .description("springboot整合swagger2")
                .termsOfServiceUrl("https://blog.csdn.net/weixin_37591536")
                .version("1.0")
                .build();
    }

}

3、接口

package com.left.controller;

import com.alibaba.dubbo.config.annotation.Reference;
import com.left.PageBean;
import com.left.Result;
import com.left.enums.ResultEnum;
import com.left.request.IdReq;
import com.left.request.repair.*;
import com.left.util.ResultUtils;
import com.left.web.dataObject.RepairSite;
import com.left.web.query.StatusPageQuery;
import com.left.web.service.RepairSiteService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.BeanUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;


/**
 * 
 *     @author : orange
 *     e-mail : [email protected]
 *     time   : 2018/7/23 10:45
 *     desc   :
 *     version: 1.0
 * 
 */
@Slf4j
@RestController
@Api(description = "维修站点相关")
@RequestMapping("/repairSite")
public class RepairSiteController {

    @Reference
    private RepairSiteService repairSiteService;

    @PostMapping("/getOne")
    @ApiOperation("查询单个维修站点信息")
    public Result getOne(@RequestBody IdReq req) throws Exception {
        RepairSite one = repairSiteService.getOne(req.getId());
        return ResultUtils.success(one);
    }


    @PostMapping("/page")
    @ApiOperation("分页查询维修站点")
    public Result pageSite(@RequestBody RepairSitePageReq req) throws Exception {
        StatusPageQuery pageQuery = new StatusPageQuery();
        BeanUtils.copyProperties(req, pageQuery);
        PageBean pageBean = repairSiteService.page(pageQuery);

        if (pageBean == null) {
            return ResultUtils.error(ResultEnum.NO_DATA);
        }
        return ResultUtils.success(pageBean);
    }

}

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

界面如下：

5、Swagger注解

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

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