后端 API 接口文档 Swagger 使用指南( 二 ) _Swagger

films = filmService.getFilmByName(fileName);if (!CollectionUtils.isEmpty(films)) {return new ResultModel(films);}return CommonConstants.getErrorResultModel();}/*** 根据电影名更新** @return*/@PostMapping("/updateScore")@ApiOperation(value = "根据电影名修改分数")@ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),@ApiResponse(code = 1002, message = "缺少参数") })public ResultModel updateFilmScore(@ApiParam("电影名称") @RequestParam("fileName") String fileName,@ApiParam("分数") @RequestParam("score") Short score) {if (StringUtils.isEmpty(fileName) || Objects.isNull(score)) {return CommonConstants.getErrorResultModel();}filmService.updateScoreByName(fileName, score);return CommonConstants.getSuccessResultModel();}/*** 根据电影名删除电影** @param request* @return*/@PostMapping("/delFilm")@ApiOperation(value = "根据电影名删除电影")@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");//电影idLong filmId = Long.parseLong(request.getParameter("id"));filmService.deleteFilmOrId(filmName,filmId);return CommonConstants.getSuccessResultModel();}/*** 根据id获取电影** @param id* @return*/@PostMapping("/{id}")@ApiOperation("根据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();}/*** 修改整个电影** @param film* @return*/@PostMapping("/insertFilm")@ApiOperation("插入一部电影")public ResultModel insertFilm(@ApiParam("电影实体对象") @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:访问本地链接

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的作用。实在是开发编程必备良品啊。