江苏龙网

  1. 主页 > 生活百科 > >

后端 API 接口文档 Swagger 使用指南

Swagger

前言作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.." 。可以看到在前后端沟通中出现了不少问题 。
对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器 。
一：swagger是什么？【后端 API 接口文档 Swagger 使用指南】Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件 。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务 。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器 。
这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件 。
二：为什么要使用swaager?2.1:对于后端开发人员来说

  • 不用再手写WiKi接口拼大量的参数，避免手写错误
  • 对代码侵入性低，采用全注解的方式，开发简单
  • 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
  • 缺点：增加了开发成本，写接口还得再写一套参数配置
2.2:对于前端开发来说
  • 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
  • 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题
2.3：对于测试
  • 对于某些没有前端界面UI的功能，可以用它来测试接口
  • 操作简单，不用了解具体代码就可以操作
  • 操作简单，不用了解具体代码就可以操作
三：如何搭一个swagger3.1:引入swagger的依赖目前推荐使用2.7.0版本,因为2.6.0版本有bug，而其他版本又没有经过验证
一：引入Swagger依赖库<!--引入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 {@Beanpublic 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的核心在于注解，接下来就着重讲一下swagger的注解：
后端 API 接口文档 Swagger 使用指南

文章插图
 
四：在项目中集成swagger4.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 = https://www.isolves.com/it/cxkf/bk/2019-12-25/"电影Controller", tags = { "电影访问接口" })@RequestMapping("/film")public class FilmController {@Autowiredprivate FilmService filmService;/*** 添加一个电影数据** @param* @return*/@ApiOperation(value = "添加一部电影")@PostMapping("/addFilm")@ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),@ApiResponse(code = 1002, response = Film.class,message = "缺少参数") })public ResultModel addFilm(@ApiParam("电影名称") @RequestParam("filmName") String filmName,@ApiParam(value = "分数", allowEmptyValue = true) @RequestParam("score") Short score,@ApiParam("发布时间") @RequestParam(value = "publishTime",required = false) String publishTime,@ApiParam("创建者id") @RequestParam("creatorId") Long creatorId) {if (Objects.isNull(filmName) || Objects.isNull(score) || Objects.isNull(publishTime) || StringUtils.isEmpty(creatorId)) {return new ResultModel(ResultModel.failed, "参数错误");}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);}/*** 根据电影名字获取电影** @param fileName* @return*/@GetMapping("/getFilms")@ApiOperation(value = "根据名字获取电影")@ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),@ApiResponse(code = 1002, message = "缺少参数") })public ResultModel getFilmsByName(@ApiParam("电影名称") @RequestParam("fileName") String fileName) {if (StringUtils.isEmpty(fileName)) {return CommonConstants.getErrorResultModel();}List


推荐阅读


上一篇：局域网成员无法正常上网的顽疾---DHCP服务器&quot;泛滥&quot;

下一篇：自己动手，DIY一台硬件WAF