Springboot集成Swagger

前言

最近新入职了一家公司，项目开发完毕发现没有写接口的API文档工具，问了一下组长，组长告诉我说平常都是口头交流调试，用不着接口文档......想着能少费点口水，于是简单就整合一个swagger2，下面贴上代码。

Jar包依赖

我们用的是Maven项目，所以直接在pom.xml中进行依赖，因为我们项目使用的Springboot-1.3.5，所以依赖比较低，如果是高版本的小伙伴，可以自行下载对应的版本依赖。

• Maven仓库传送门

 <!-- swagger2-->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.4.0</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.4.0</version>

</dependency>

配置类

然后我们需要新建一个swagger配置类

package net.XXXX.xx.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.schema.ModelRef;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

import springfox.documentation.service.Parameter;

import springfox.documentation.builders.ParameterBuilder;

import java.util.ArrayList;

import java.util.List;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("net.XXX.xx"))//这里是自己的包结构

                .paths(PathSelectors.any())

                .build()

                .globalOperationParameters(globalOperation());

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("接口示例文档")

                .description("接口文档Demo")

                .version("1.0")

                .build();

    }

    //下面代码可以酌情处理，因为我们接口需要有token验证，所以需要配置一下token输入框，下面代码就是做这个功能的

    private List<Parameter> globalOperation(){

        //添加head参数配置start

        ParameterBuilder tokenPar = new ParameterBuilder();

        List<Parameter> pars = new ArrayList<>();

        //第一个token为传参的key，第二个token为swagger页面显示的值

        tokenPar.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();

        pars.add(tokenPar.build());

        return pars;

    }

}

注意

如果大家项目中有过滤器，需要将swagger的访问地址释放掉，将以下地址进行释放。

swagger-resources/*

swagger-ui.html/*

v2/*

webjars/*

示例Controller

这里我们用一个GET请求做一下示例，标注一下Controller以及参数，请忽略代码内容～

@Api(value = "RevenueBudgetReisterController", description = "收入预算登记API")
@RestController
@RequestMapping("/revenueBudgetRegister")
public class RevenueBudgetReisterController extends BaseController {

    private RevenueBudgetRegisterService registerService;

    @Autowired
    public RevenueBudgetReisterController(RevenueBudgetRegisterService registerService) {
        this.registerService = registerService;
    }


    @ApiOperation(value = "获取收入预算明细记录", notes="获取收入预算明细记录列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "year", value = "年份", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "dictionaryName", value = "科目名称", required = false, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "departmentId", value = "部门ID", required = true, dataType = "String", paramType = "query")
    })
    @RequestMapping(value = "/v1.0/revenueBudgetTetails", method = RequestMethod.GET)
    public ResultDto revenueBudgetTetails(String year, String dictionaryName, String departmentId, HttpServletRequest request) {
        try {
            if (null == year || year.equals("")
                    || null == departmentId || "".equals(departmentId)) {
                return new ResultDto(ResultDto.CODE_FAIL, RevenueBudgetDetailsController.ERROR_DATA, null);
            }
            List<RevenueBudgetDetailsRespVo> details = registerService.details(year, dictionaryName, departmentId, getCurrentUser(request));
            return new ResultDto(ResultDto.CODE_SUCCESS, RevenueBudgetDetailsController.SUCCEEDED, details);
        } catch (Exception e) {
            return new ResultDto(ResultDto.CODE_FAIL, e.getMessage(), null);
        }
    }
」

项目启动

访问地址：http://localhost:8006/swagger-ui.html#/地址端口号大家请更改为与自己相对应的，我这里设置的是8006

​

bingo！～ 出现这个界面就表示成功了！( 老汉激动摸了摸自己的秃头，从轮椅上站了起来，流下了开心的泪水.....)

​

然后我们随便点进去一个

​

这里会显示我们接口的入参，以及请求方式等信息，如果我们配置了token输入框，这里则会显示出来。

关于启动问题

可能集成swagger会出现下面这个异常。​

集成swagger2报错：

java.lang.NoSuchMethodError: com.google.common.XXX

出现这个异常是因为swagger中内置了一个谷歌的guava包，而项目中也有guava的依赖，版本不一致导致的冲突，我们需要将版本进行匹配，或者将低版本的依赖给排除掉，我这里降低了版本，本来项目中依赖的是swagger-2.9.2的版本，于是降低到了swagger-2.4.0版本，完美解决～

Swagger常用注解

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

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

本次教程就到这里了，谢谢大家阅读， 写的有不对的地方还请多多包涵以及提出！
                                                                                              原创文章，转载请标明出处