Spring Boot集成 Swagger2 展现在线接口文档

谁借莪１个温暖的怀抱￠ 2024-03-27 11:36 65阅读 0赞

### 一：swagger是什么？ ###

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

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

### 二：为什么要使用swaager? ###

### 2.1:对于后端开发人员来说 ###

*  不用再手写WiKi接口拼大量的参数，避免手写错误
 *  对代码侵入性低，采用全注解的方式，开发简单
 *  方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
 *  缺点：增加了开发成本，写接口还得再写一套参数配置

### 2.2:对于前端开发来说 ###

*  后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
 *  联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

### 2.3：对于测试 ###

*  对于某些没有前端界面UI的功能，可以用它来测试接口
 *  操作简单，不用了解具体代码就可以操作
 *  操作简单，不用了解具体代码就可以操作

### 三：如何搭一个swagger ###

### 3.1:引入swagger的依赖 ###

目前推荐使用2.2.2 版本

<dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.2.2</version>
    </dependency>
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger-ui</artifactId>
    	<version>2.2.2</version>
    </dependency>

### 3.2：springBoot整合swagger ###

新建一个配置类，Swagger2 的配置类上除了添加必要的 `@Configuration` 注解外，还需要添加 `@EnableSwagger2` 注解。

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.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
     
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
     
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    // 指定构建api文档的详细信息的方法：apiInfo()
                    .apiInfo(apiInfo())
                    .select()
                    // 指定要生成api接口的包路径，这里把controller作为包路径，生成controller中的所有接口
                    .apis(RequestHandlerSelectors.basePackage("com.itcodai.course06.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
     
        /**
         * 构建api文档的详细信息
         * @return
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    // 设置页面标题
                    .title("Spring Boot集成Swagger2接口总览")
                    // 设置接口描述
                    .description("学Spring Boot")
                    // 设置联系方式
                    .contact("Myovlmx" + "CSDN：http://blog.csdn.net/eson_15")
                    // 设置版本
                    .version("1.0")
                    // 构建
                    .build();
        }
    }

到此为止，我们已经配置好了 Swagger2 了。现在我们可以测试一下配置有没有生效，启动项目，在浏览器中输入 `localhost:8080/swagger-ui.html`，即可看到 swagger2 的接口页面，如下图所示，说明Swagger2 集成成功。

![5f2f11a709db4f11aef90c67652e3dad.png][]

### 四：在项目中集成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 = { "电影访问接口" })
    @RequestMapping("/film")
    public class FilmController {
    
        @Autowired
        private 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<Film> 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");
            //电影id
            Long 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就可以进行接口测试

[5f2f11a709db4f11aef90c67652e3dad.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/8fdba5f9b0394f1a8ba3369b4e283499.png