swagger使用指南

 

 

做者：Yrion

 

前言：做为一个之前后端分离为模式开发小组，咱们每隔一段时间都进行这样一个场景：前端人员和后端开发在一块儿热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。能够看到在先后端沟通中出现了很多问题。

对于这样的问题,以前一直没有很好的解决方案，直到它的出现，没错...这就是咱们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

目录

• swagger是什么？

• 为何要使用swaager?

• 如何搭一个swagger？

• 如何在项目中集成swagger

• 使用swagger须要注意的问题

• 总结

一：swagger是什么？

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统做为服务器以一样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来说就是说，swagger是一款能够根据resutful风格生成的生成的接口开发文档，而且支持作测试的一款中间软件。

二：为何要使用swaager?

2.1:对于后端开发人员来讲

• 不用再手写WiKi接口拼大量的参数，避免手写错误

• 对代码侵入性低，采用全注解的方式，开发简单

• 方法参数名修改、增长、减小参数均可以直接生效，不用手动维护

• 缺点：增长了开发成本，写接口还得再写一套参数配置

2.2:对于前端开发来讲

• 后端只须要定义好接口，会自动生成文档，接口功能、参数一目了然

• 联调方便，若是出问题，直接测试接口，实时检查参数和返回值,就能够快速定位是前端仍是后端的问题

2.3：对于测试

• 对于某些没有前端界面UI的功能，能够用它来测试接口

• 操做简单，不用了解具体代码就能够操做

• 操做简单，不用了解具体代码就能够操做

三：如何搭一个swagger

3.1:引入swagger的依赖

目前推荐使用2.7.0版本,由于2.6.0版本有bug，而其余版本又没有通过验证

1. <!--引入swagger-->

2. <dependency>

3.    <groupId>io.springfox</groupId>

4.    <artifactId>springfox-swagger2</artifactId>

5.    <version>2.7.0</version>

6. </dependency>

7. <dependency>

8.    <groupId>io.springfox</groupId>

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

10.    <version>2.7.0</version>

11. </dependency>

3.2：springBoot整合swagger

1. @Configuration

2. @EnableSwagger2

3. public class SwaggerConfig {

4.    @Bean

5.    public Docket productApi() {

6.        return new Docket(DocumentationType.SWAGGER_2)

7.                .apiInfo(apiInfo())

8.                .select()

9.                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被扫描

10.                .paths(PathSelectors.any())

11.                .build();

12.  

13.    }

14.  

15.    private ApiInfo apiInfo() {

16.        return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文档")

17.                .version("1.0").build();

18.    }

19.  

20. }

3.3：swagger的注解

swagger的核心在于注解，接下来就着重讲一下swagger的注解：

四：在项目中集成swagger

4.1:在controller中使用注解

1. package com.youjia.swagger.controller;

2.  

3. import com.youjia.swagger.constants.CommonConstants;

4. import com.youjia.swagger.model.Film;

5. import com.youjia.swagger.model.ResultModel;

6. import com.youjia.swagger.service.FilmService;

7. import io.swagger.annotations.Api;

8. import io.swagger.annotations.ApiImplicitParam;

9. import io.swagger.annotations.ApiImplicitParams;

10. import io.swagger.annotations.ApiOperation;

11. import io.swagger.annotations.ApiParam;

12. import io.swagger.annotations.ApiResponse;

13. import io.swagger.annotations.ApiResponses;

14. import org.springframework.beans.factory.annotation.Autowired;

15. import org.springframework.util.CollectionUtils;

16. import org.springframework.util.StringUtils;

17. import org.springframework.web.bind.annotation.GetMapping;

18. import org.springframework.web.bind.annotation.PathVariable;

19. import org.springframework.web.bind.annotation.PostMapping;

20. import org.springframework.web.bind.annotation.RequestBody;

21. import org.springframework.web.bind.annotation.RequestMapping;

22. import org.springframework.web.bind.annotation.RequestParam;

23. import org.springframework.web.bind.annotation.RestController;

24.  

25. import javax.servlet.http.HttpServletRequest;

26. import java.text.DateFormat;

27. import java.text.SimpleDateFormat;

28. import java.util.Date;

29. import java.util.List;

30. import java.util.Objects;

31.  

32. /**

33. * @Auther: wyq

34. * @Date: 2018/12/29 14:50

35. */

36. @RestController

37. @Api(value = "电影Controller", tags = { "电影访问接口" })

38. @RequestMapping("/film")

39. public class FilmController {

40.  

41.    @Autowired

42.    private FilmService filmService;

43.  

44.    /**

45.     * 添加一个电影数据

46.     *

47.     * @param

48.     * @return

49.     */

50.    @ApiOperation(value = "添加一部电影")

51.    @PostMapping("/addFilm")

52.    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),

53.            @ApiResponse(code = 1002, response = Film.class,message = "缺乏参数") })

54.    public ResultModel addFilm(@ApiParam("电影名称") @RequestParam("filmName") String filmName,

55.                               @ApiParam(value = "分数", allowEmptyValue = true) @RequestParam("score") Short score,

56.                               @ApiParam("发布时间") @RequestParam(value = "publishTime",required = false) String publishTime,

57.                               @ApiParam("建立者id") @RequestParam("creatorId") Long creatorId) {

58.  

59.        if (Objects.isNull(filmName) || Objects.isNull(score) || Objects.isNull(publishTime) || StringUtils

60.                .isEmpty(creatorId)) {

61.            return new ResultModel(ResultModel.failed, "参数错误");

62.        }

63.        Film filmPOM = new Film();

64.        filmPOM.setFilmName(filmName);

65.        filmPOM.setScore(score);

66.        DateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");

67.        Date publishTimeDate = null;

68.        try {

69.            publishTimeDate = simpleDateFormat.parse(publishTime);

70.        } catch (Exception ex) {

71.            ex.printStackTrace();

72.        }

73.        filmPOM.setPublishTime(publishTimeDate);

74.        filmPOM.setCreatorId(creatorId);

75.        Boolean result = filmService.addFilm(filmPOM);

76.        if (result) {

77.            return new ResultModel(CommonConstants.SUCCESSMSG);

78.        }

79.        return new ResultModel(CommonConstants.FAILD_MSG);

80.    }

81.  

82.    /**

83.     * 根据电影名字获取电影

84.     *

85.     * @param fileName

86.     * @return

87.     */

88.    @GetMapping("/getFilms")

89.    @ApiOperation(value = "根据名字获取电影")

90.    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),

91.            @ApiResponse(code = 1002, message = "缺乏参数") })

92.    public ResultModel getFilmsByName(@ApiParam("电影名称") @RequestParam("fileName") String fileName) {

93.        if (StringUtils.isEmpty(fileName)) {

94.            return CommonConstants.getErrorResultModel();

95.        }

96.  

97.        List<Film> films = filmService.getFilmByName(fileName);

98.        if (!CollectionUtils.isEmpty(films)) {

99.            return new ResultModel(films);

100.        }

101.        return CommonConstants.getErrorResultModel();

102.  

103.    }

104.  

105.    /**

106.     * 根据电影名更新

107.     *

108.     * @return

109.     */

110.    @PostMapping("/updateScore")

111.    @ApiOperation(value = "根据电影名修改分数")

112.    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),

113.            @ApiResponse(code = 1002, message = "缺乏参数") })

114.    public ResultModel updateFilmScore(@ApiParam("电影名称") @RequestParam("fileName") String fileName,

115.                                       @ApiParam("分数") @RequestParam("score") Short score) {

116.        if (StringUtils.isEmpty(fileName) || Objects.isNull(score)) {

117.            return CommonConstants.getErrorResultModel();

118.        }

119.  

120.        filmService.updateScoreByName(fileName, score);

121.        return CommonConstants.getSucce***esultModel();

122.    }

123.  

124.    /**

125.     * 根据电影名删除电影

126.     *

127.     * @param request

128.     * @return

129.     */

130.    @PostMapping("/delFilm")

131.    @ApiOperation(value = "根据电影名删除电影")

132.    @ApiImplicitParams({ @ApiImplicitParam(name = "filmName",

133.            value = "电影名",

134.            dataType = "String",

135.            paramType = "query",

136.            required = true), @ApiImplicitParam(name = "id", value = "电影id", dataType = "int", paramType = "query") })

137.    public ResultModel deleteFilmByNameOrId(HttpServletRequest request) {

138.        //电影名

139.        String filmName = request.getParameter("filmName");

140.        //电影id

141.        Long filmId = Long.parseLong(request.getParameter("id"));

142.  

143.        filmService.deleteFilmOrId(filmName,filmId);

144.  

145.  

146.        return CommonConstants.getSucce***esultModel();

147.    }

148.  

149.    /**

150.     * 根据id获取电影

151.     *

152.     * @param id

153.     * @return

154.     */

155.    @PostMapping("/{id}")

156.    @ApiOperation("根据id获取电影")

157.    @ApiImplicitParam(name = "id", value = "电影id", dataType = "long", paramType = "path", required = true)

158.    public ResultModel getFilmById(@PathVariable Long id) {

159.  

160.        if (Objects.isNull(id)) {

161.            return CommonConstants.getLessParamResultModel();

162.        }

163.        Film film = filmService.getFilmById(id);

164.        if (Objects.nonNull(film)) {

165.            return new ResultModel(film);

166.        }

167.        return CommonConstants.getErrorResultModel();

168.    }

169.  

170.    /**

171.     * 修改整个电影

172.     *

173.     * @param film

174.     * @return

175.     */

176.    @PostMapping("/insertFilm")

177.    @ApiOperation("插入一部电影")

178.    public ResultModel insertFilm(@ApiParam("电影实体对象") @RequestBody Film film) {

179.        if (Objects.isNull(film)) {

180.            return CommonConstants.getLessParamResultModel();

181.        }

182.        Boolean isSuccess = filmService.insertFilm(film);

183.        if (isSuccess) {

184.            return CommonConstants.getSucce***esultModel();

185.        }

186.        return CommonConstants.getErrorResultModel();

187.    }

188. }

4.2:访问本地连接

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

能够看出访问的url都很清晰的展现在它最终的页面上，咱们打开一个方法：能够看出方法的请求参数清晰的的罗列出来，包括方法的返回值。而且有一个很重要的功能，只须要点下方的try it out就能够进行接口测试，

五：使用swagger须要注意的问题

• 对于只有一个HttpServletRequest参数的方法,若是参数小于5个，推荐使用 @ApiImplicitParams的方式单独封装每个参数；若是参数大于5个，采用定义一个对象去封装全部参数的属性，而后使用@APiParam的方式

• 默认的访问地址：ip:port/swagger-ui.html#/,可是在shiro中,会拦截全部的请求，必须加上默认访问路径（好比项目中，就是ip:port/context/swagger-ui.html#/），而后登录后才能够看到

• 在GET请求中，参数在Body体里面,不能使用@RequestBody。在POST请求，可使用@RequestBody和@RequestParam，若是使用@RequestBody，对于参数转化的配置必须统一

• controller必须指定请求类型，不然swagger会把全部的类型(6种)都生成出来

• swagger在生产环境不能对外暴露,可使用@Profile({“dev”, “prod”,“pre”})指定可使用的环境

六：总结

swagger做为一款辅助性的工具，能大大提高咱们的和前端的沟通效率,接口是一个很是重要的传递数据的媒介，每一个接口的签名、方法参数都很是重要。一个良好的文档很是重要，若是采用手写的方式很是容易拼写错误，而swagger能够自动化生成参数文档，这一切都加快了咱们的沟通效率。而且能够替代postman的做用。实在是开发编程必备良品啊。