Springboot集成Swagger

前言

最近新入職了一家公司冈涧，項(xiàng)目開發(fā)完畢發(fā)現(xiàn)沒有寫接口的API文檔工具，問了一下組長，組長告訴我說平常都是口頭交流調(diào)試钞支，用不著接口文檔......想著能少費(fèi)點(diǎn)口水，于是簡單就整合一個(gè)swagger2操刀，下面貼上代碼烁挟。

Jar包依賴

我們用的是Maven項(xiàng)目，所以直接在pom.xml中進(jìn)行依賴骨坑，因?yàn)槲覀冺?xiàng)目使用的Springboot-1.3.5撼嗓，所以依賴比較低，如果是高版本的小伙伴，可以自行下載對(duì)應(yīng)的版本依賴且警。

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>

配置類

然后我們需要新建一個(gè)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"))//這里是自己的包結(jié)構(gòu)

                .paths(PathSelectors.any())

                .build()

                .globalOperationParameters(globalOperation());

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

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

                .description("接口文檔Demo")

                .version("1.0")

                .build();

    }

    //下面代碼可以酌情處理粉捻，因?yàn)槲覀兘涌谛枰衪oken驗(yàn)證，所以需要配置一下token輸入框斑芜，下面代碼就是做這個(gè)功能的

    private List<Parameter> globalOperation(){

        //添加head參數(shù)配置start

        ParameterBuilder tokenPar = new ParameterBuilder();

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

        //第一個(gè)token為傳參的key肩刃，第二個(gè)token為swagger頁面顯示的值

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

        pars.add(tokenPar.build());

        return pars;

    }

}

注意

如果大家項(xiàng)目中有過濾器，需要將swagger的訪問地址釋放掉押搪，將以下地址進(jìn)行釋放树酪。

swagger-resources/*

swagger-ui.html/*

v2/*

webjars/*

示例Controller

這里我們用一個(gè)GET請求做一下示例，標(biāo)注一下Controller以及參數(shù)大州，請忽略代碼內(nèi)容～

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

    private RevenueBudgetRegisterService registerService;

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


    @ApiOperation(value = "獲取收入預(yù)算明細(xì)記錄", notes="獲取收入預(yù)算明細(xì)記錄列表")
    @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);
        }
    }
」

項(xiàng)目啟動(dòng)

訪問地址：http://localhost:8006/swagger-ui.html#/地址端口號(hào)大家請更改為與自己相對(duì)應(yīng)的续语，我這里設(shè)置的是8006

bingo！～出現(xiàn)這個(gè)界面就表示成功了厦画！( 老漢激動(dòng)摸了摸自己的禿頭疮茄，從輪椅上站了起來，流下了開心的淚水.....)

然后我們隨便點(diǎn)進(jìn)去一個(gè)

這里會(huì)顯示我們接口的入?yún)⒏睿约罢埱蠓绞降刃畔⒘κ裕绻覀兣渲昧藅oken輸入框，這里則會(huì)顯示出來排嫌。

關(guān)于啟動(dòng)問題

可能集成swagger會(huì)出現(xiàn)下面這個(gè)異常畸裳。?

集成swagger2報(bào)錯(cuò)：

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

出現(xiàn)這個(gè)異常是因?yàn)閟wagger中內(nèi)置了一個(gè)谷歌的guava包，而項(xiàng)目中也有g(shù)uava的依賴淳地，版本不一致導(dǎo)致的沖突怖糊，我們需要將版本進(jìn)行匹配，或者將低版本的依賴給排除掉颇象，我這里降低了版本伍伤，本來項(xiàng)目中依賴的是swagger-2.9.2的版本，于是降低到了swagger-2.4.0版本遣钳，完美解決～

Swagger常用注解

swagger通過注解表明該接口會(huì)生成文檔扰魂，包括接口名、請求方法蕴茴、參數(shù)劝评、返回信息的等等。

@Api：修飾整個(gè)類倦淀，描述Controller的作用
@ApiOperation：描述一個(gè)類的一個(gè)方法付翁，或者說一個(gè)接口
@ApiParam：單個(gè)參數(shù)描述
@ApiModel：用對(duì)象來接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiParamImplicitL：一個(gè)請求參數(shù)
@ApiParamsImplicit ：多個(gè)請求參數(shù)
@ApiImplicitParams：用在請求的方法上晃听，表示一組參數(shù)說明
@ApiImplicitParam：參數(shù)說明百侧，用在@ApiImplicitParams中

本次教程就到這里了砰识，謝謝大家閱讀，寫的有不對(duì)的地方還請多多包涵以及提出佣渴！
??????????????????????????????????????????????????????????????????????????????????????????????原創(chuàng)文章辫狼，轉(zhuǎn)載請標(biāo)明出處