前言

作為一個(gè)以前后端分離為模式開(kāi)發(fā)小組，我們每隔一段時(shí)間都進(jìn)行這樣一個(gè)場(chǎng)景：前端人員和后端開(kāi)發(fā)在一起熱烈的討論"哎,你這參數(shù)又變了啊","接口怎么又請(qǐng)求不通了啊","你再試試,我打個(gè)斷點(diǎn)調(diào)試一下.."?？梢钥吹皆谇昂蠖藴贤ㄖ谐霈F(xiàn)了不少問(wèn)題。

對(duì)于這樣的問(wèn)題,之前一直沒(méi)有很好的解決方案，直到它的出現(xiàn)，沒(méi)錯(cuò)...這就是我們今天要討論的神器:swagger,一款致力于解決接口規(guī)范化、標(biāo)準(zhǔn)化、文檔化的開(kāi)源庫(kù)，一款真正的開(kāi)發(fā)神器。

一：swagger是什么？

Swagger是一款RESTFUL接口的文檔在線自動(dòng)生成+功能測(cè)試功能軟件。Swagger是一個(gè)規(guī)范和完整的框架,用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。目標(biāo)是使客戶(hù)端和文件系統(tǒng)作為服務(wù)器以同樣的速度來(lái)更新文件的方法,參數(shù)和模型緊密集成到服務(wù)器。

這個(gè)解釋簡(jiǎn)單點(diǎn)來(lái)講就是說(shuō)，swagger是一款可以根據(jù)resutful風(fēng)格生成的生成的接口開(kāi)發(fā)文檔，并且支持做測(cè)試的一款中間軟件。

二：為什么要使用swaager?

2.1:對(duì)于后端開(kāi)發(fā)人員來(lái)說(shuō)

• 不用再手寫(xiě)WiKi接口拼大量的參數(shù)，避免手寫(xiě)錯(cuò)誤
• 對(duì)代碼侵入性低，采用全注解的方式，開(kāi)發(fā)簡(jiǎn)單
• 方法參數(shù)名修改、增加、減少參數(shù)都可以直接生效，不用手動(dòng)維護(hù)
• 缺點(diǎn)：增加了開(kāi)發(fā)成本，寫(xiě)接口還得再寫(xiě)一套參數(shù)配置

2.2:對(duì)于前端開(kāi)發(fā)來(lái)說(shuō)

• 后端只需要定義好接口，會(huì)自動(dòng)生成文檔，接口功能、參數(shù)一目了然
• 聯(lián)調(diào)方便，如果出問(wèn)題，直接測(cè)試接口，實(shí)時(shí)檢查參數(shù)和返回值,就可以快速定位是前端還是后端的問(wèn)題

2.3：對(duì)于測(cè)試

• 對(duì)于某些沒(méi)有前端界面UI的功能，可以用它來(lái)測(cè)試接口
• 操作簡(jiǎn)單，不用了解具體代碼就可以操作
• 操作簡(jiǎn)單，不用了解具體代碼就可以操作

三：如何搭一個(gè)swagger

3.1:引入swagger的依賴(lài)

目前推薦使用2.7.0版本,因?yàn)?.6.0版本有bug，而其他版本又沒(méi)有經(jīng)過(guò)驗(yàn)證

一：引入Swagger依賴(lài)庫(kù)<!--引入swagger--><dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.7.0</version></dependency><dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger-ui</artifactId>    <version>2.7.0</version></dependency>

3.2：springBoot整合swagger

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket productApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被掃描                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文檔")                .version("1.0").build();    }}

3.3：swagger的注解

swagger的核心在于注解，接下來(lái)就著重講一下swagger的注解：

四：在項(xiàng)目中集成swagger

4.1:在controller中使用注解

package com.youjia.swagger.controller;import com.youjia.swagger.constants.CommonConstants;import com.youjia.swagger.model.Film;import com.youjia.swagger.model.ResultModel;import com.youjia.swagger.service.FilmService;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import io.swagger.annotations.ApiResponse;import io.swagger.annotations.ApiResponses;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.util.CollectionUtils;import org.springframework.util.StringUtils;import org.springframework.web.bind.annotation.GetMApping;import org.springframework.web.bind.annotation.PathVariable;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.RequestParam;import org.springframework.web.bind.annotation.RestController;import JAVAx.servlet.http.HttpServletRequest;import java.text.DateFormat;import java.text.SimpleDateFormat;import java.util.Date;import java.util.List;import java.util.Objects;/** * @Auther: wyq * @Date: 2018/12/29 14:50 */@RestController@Api(value = "電影Controller", tags = { "電影訪問(wèn)接口" })@RequestMapping("/film")public class FilmController {    @Autowired    private FilmService filmService;    /**     * 添加一個(gè)電影數(shù)據(jù)     *     * @param     * @return     */    @ApiOperation(value = "添加一部電影")    @PostMapping("/addFilm")    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失敗"),            @ApiResponse(code = 1002, response = Film.class,message = "缺少參數(shù)") })    public ResultModel addFilm(@ApiParam("電影名稱(chēng)") @RequestParam("filmName") String filmName,                               @ApiParam(value = "分?jǐn)?shù)", allowEmptyValue = true) @RequestParam("score") Short score,                               @ApiParam("發(fā)布時(shí)間") @RequestParam(value = "publishTime",required = false) String publishTime,                               @ApiParam("創(chuàng)建者id") @RequestParam("creatorId") Long creatorId) {        if (Objects.isNull(filmName) || Objects.isNull(score) || Objects.isNull(publishTime) || StringUtils                .isEmpty(creatorId)) {            return new ResultModel(ResultModel.failed, "參數(shù)錯(cuò)誤");        }        Film filmPOM = new Film();        filmPOM.setFilmName(filmName);        filmPOM.setScore(score);        DateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");        Date publishTimeDate = null;        try {            publishTimeDate = simpleDateFormat.parse(publishTime);        } catch (Exception ex) {            ex.printStackTrace();        }        filmPOM.setPublishTime(publishTimeDate);        filmPOM.setCreatorId(creatorId);        Boolean result = filmService.addFilm(filmPOM);        if (result) {            return new ResultModel(CommonConstants.SUCCESSMSG);        }        return new ResultModel(CommonConstants.FAILD_MSG);    }    /**     * 根據(jù)電影名字獲取電影     *     * @param fileName     * @return     */    @GetMapping("/getFilms")    @ApiOperation(value = "根據(jù)名字獲取電影")    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失敗"),            @ApiResponse(code = 1002, message = "缺少參數(shù)") })    public ResultModel getFilmsByName(@ApiParam("電影名稱(chēng)") @RequestParam("fileName") String fileName) {        if (StringUtils.isEmpty(fileName)) {            return CommonConstants.getErrorResultModel();        }        List<Film> films = filmService.getFilmByName(fileName);        if (!CollectionUtils.isEmpty(films)) {            return new ResultModel(films);        }        return CommonConstants.getErrorResultModel();    }    /**     * 根據(jù)電影名更新     *     * @return     */    @PostMapping("/updateScore")    @ApiOperation(value = "根據(jù)電影名修改分?jǐn)?shù)")    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失敗"),            @ApiResponse(code = 1002, message = "缺少參數(shù)") })    public ResultModel updateFilmScore(@ApiParam("電影名稱(chēng)") @RequestParam("fileName") String fileName,                                       @ApiParam("分?jǐn)?shù)") @RequestParam("score") Short score) {        if (StringUtils.isEmpty(fileName) || Objects.isNull(score)) {            return CommonConstants.getErrorResultModel();        }        filmService.updateScoreByName(fileName, score);        return CommonConstants.getSuccessResultModel();    }    /**     * 根據(jù)電影名刪除電影     *     * @param request     * @return     */    @PostMapping("/delFilm")    @ApiOperation(value = "根據(jù)電影名刪除電影")    @ApiImplicitParams({ @ApiImplicitParam(name = "filmName",            value = "電影名",            dataType = "String",            paramType = "query",            required = true), @ApiImplicitParam(name = "id", value = "電影id", dataType = "int", paramType = "query") })    public ResultModel deleteFilmByNameOrId(HttpServletRequest request) {        //電影名        String filmName = request.getParameter("filmName");        //電影id        Long filmId = Long.parseLong(request.getParameter("id"));        filmService.deleteFilmOrId(filmName,filmId);        return CommonConstants.getSuccessResultModel();    }    /**     * 根據(jù)id獲取電影     *     * @param id     * @return     */    @PostMapping("/{id}")    @ApiOperation("根據(jù)id獲取電影")    @ApiImplicitParam(name = "id", value = "電影id", dataType = "long", paramType = "path", required = true)    public ResultModel getFilmById(@PathVariable Long id) {        if (Objects.isNull(id)) {            return CommonConstants.getLessParamResultModel();        }        Film film = filmService.getFilmById(id);        if (Objects.nonNull(film)) {            return new ResultModel(film);        }        return CommonConstants.getErrorResultModel();    }    /**     * 修改整個(gè)電影     *     * @param film     * @return     */    @PostMapping("/insertFilm")    @ApiOperation("插入一部電影")    public ResultModel insertFilm(@ApiParam("電影實(shí)體對(duì)象") @RequestBody Film film) {        if (Objects.isNull(film)) {            return CommonConstants.getLessParamResultModel();        }        Boolean isSuccess = filmService.insertFilm(film);        if (isSuccess) {            return CommonConstants.getSuccessResultModel();        }        return CommonConstants.getErrorResultModel();    }}

4.2:訪問(wèn)本地鏈接

http://localhost:8080/swagger-ui.html#/

可以看出訪問(wèn)的url都很清晰的展示在它最終的頁(yè)面上，我們打開(kāi)一個(gè)方法：可以看出方法的請(qǐng)求參數(shù)清晰的的羅列出來(lái)，包括方法的返回值。并且有一個(gè)很重要的功能，只需要點(diǎn)下方的try it out就可以進(jìn)行接口測(cè)試，

五：使用swagger需要注意的問(wèn)題

• 對(duì)于只有一個(gè)HttpServletRequest參數(shù)的方法,如果參數(shù)小于5個(gè)，推薦使用 @ApiImplicitParams的方式單獨(dú)封裝每一個(gè)參數(shù)；如果參數(shù)大于5個(gè)，采用定義一個(gè)對(duì)象去封裝所有參數(shù)的屬性，然后使用@APiParam的方式
• 默認(rèn)的訪問(wèn)地址：ip:port/swagger-ui.html#/,但是在shiro中,會(huì)攔截所有的請(qǐng)求，必須加上默認(rèn)訪問(wèn)路徑（比如項(xiàng)目中，就是ip:port/context/swagger-ui.html#/），然后登陸后才可以看到
• 在GET請(qǐng)求中，參數(shù)在Body體里面,不能使用@RequestBody。在POST請(qǐng)求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，對(duì)于參數(shù)轉(zhuǎn)化的配置必須統(tǒng)一
• controller必須指定請(qǐng)求類(lèi)型，否則swagger會(huì)把所有的類(lèi)型(6種)都生成出來(lái)
• swagger在生產(chǎn)環(huán)境不能對(duì)外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的環(huán)境

六：總結(jié)

swagger作為一款輔助性的工具，能大大提升我們的和前端的溝通效率,接口是一個(gè)非常重要的傳遞數(shù)據(jù)的媒介，每個(gè)接口的簽名、方法參數(shù)都非常重要。一個(gè)良好的文檔非常重要，如果采用手寫(xiě)的方式非常容易拼寫(xiě)錯(cuò)誤，而swagger可以自動(dòng)化生成參數(shù)文檔，這一切都加快了我們的溝通效率。并且可以替代postman的作用。實(shí)在是開(kāi)發(fā)編程必備良品啊。