springboot2.x集成Swagger3

水深无声 2022-12-27 12:37 205阅读 0赞

### 目的： ###

在写这篇记录时，swagger的最新版本到了3.0.0了，在进行集成时，没注意，还按照2.0的集成，走了一些弯路，这里特记录下。

### 环境： ###

一个已经搭建好的干净的springboot框架，这个框架中我集成了mybatis.

### 什么是swagger？ ###

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。

一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。

说的再简单点，传统的我们开发好接口后，都会通过单元测试或者如PostMan之类的测试工具进行接口的测试，在接口少的时候这个还行，可是现在大家都倡导前后端分离式的开发

导致后端全是接口，随着业务的复杂，一个项目路的 接口不要太多，每个接口我们都要去写文档，而且在过程中随着业务的编写接口还会不停的更新，这样我们的测试工具就显得力不从心了，而且大家也知道，很多公司的文档都是后补的，各种各样的原因导致可能文档中的接口与实际的接口差别还挺大。。。。。

那么这个时候，我们通过swagger的引入，在写接口的同时，通过注解的方式在接口上写明接口的作用，参数介绍等，那么会在线生成一个接口 文档，而且还可以直接进行测试，还是随着实际的接口变动实时更新的，这个是不是挺美的。这就是swagger

但是swagger是侵入式的，说白了，你要用它，就得在每个对应的接口的地方都要写点注解，虽然少，但还是有，这就侵入了我们现有的代码，这点目前看来不是很友好。

### springBoot集成swagger ###

**第一步：引入maven依赖，在你项目的pom文件中，引入下面依赖：**

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>

**第二步：添加配置，我再启动类的同级目录下添加swagger的配置类，**

package com.nj.appserver;
    
    import io.swagger.annotations.ApiOperation;
    import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
    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.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    /**
     * Swagger3配置类
     */
    @Configuration
    public class Swagger3Config {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
    
        }
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger3接口文档")
                    .description("更多请咨询服务开发者XXX")
                    .contact(new Contact("作者", "作者地址", "作者邮箱"))
                    .version("1.0")
                    .termsOfServiceUrl("aaa")
                    .build();
    
        }
    }

**第三步：在Application启动应用类上面加入@EnableOpenApi注解**

package com.nj.appserver;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    
    @EnableOpenApi
    @SpringBootApplication
    public class AppServerApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(AppServerApplication.class, args);
        }
    
    }

**第四步：在业务接口中添加swagger注解**

package com.nj.appserver.controller;
    
    import com.github.pagehelper.PageHelper;
    import com.github.pagehelper.PageInfo;
    
    import com.nj.appserver.pojo.SysUser;
    import com.nj.appserver.service.SysUserService;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.List;
    @Api(value = "用户管理接口",tags = "用户信息接口类")
    @RestController
    @RequestMapping("sysUser")
    public class SysUserController {
    
        @Autowired
        private SysUserService sysUserService;
        /**
         * 查询
         * @return
         */
        @ApiOperation("查询用户列表")
        @GetMapping("/findUserList")
        public List<SysUser> selectUserList(){
            List<SysUser> userList = sysUserService.selectUserList();
            return userList;
        }
    
        /**
         * 分页查询
         * @param pageNum 当前页数
         * @param pageSize 每页的记录条数
         * @return
         */
        @ApiOperation("分页查询用户列表")
        @GetMapping("/findUserListByPage")
        public PageInfo<SysUser> getUserBySearch(
                @RequestParam("pageNum") int pageNum,
                @RequestParam("pageSize") int pageSize) {
            // TODO Auto-generated method stub
            PageHelper.startPage(pageNum,pageSize);
            List<SysUser> list= sysUserService.selectUserList();
            PageInfo<SysUser> pageInfo = new PageInfo(list);
            pageInfo.toString();
            return pageInfo;
        }
    }

第五步：启动项目，访问swaggerui界面，注意，swagger3更新后，可访问ui界面路径与之前不同；

[http://localhost:【端口号】/\[content-path\]/swagger-ui/index.html][http_localhost_content-path_swagger-ui_index.html]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l5ajEwODMxNw_size_16_color_FFFFFF_t_70][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l5ajEwODMxNw_size_16_color_FFFFFF_t_70 1][]

--------------------

附：常用的swagger注解

@Api：用在请求的类上，表示对类的说明
    
      tags="说明该类的作用，可以在UI界面上看到的注解"
    
      value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
    
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
    
      value="说明方法的用途、作用"
    
      notes="方法的备注说明"
    
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
    
      @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    
        name：参数名
    
        value：参数的汉字说明、解释
    
        required：参数是否必须传
    
        paramType：参数放在哪个地方
    
          · header --> 请求参数的获取：@RequestHeader
    
          · query --> 请求参数的获取：@RequestParam
    
          · path（用于restful接口）--> 请求参数的获取：@PathVariable
    
          · body（不常用）
    
          · form（不常用） 
    
        dataType：参数类型，默认String，其它值dataType="Integer"   
    
        defaultValue：参数的默认值
    
    @ApiResponses：用在请求的方法上，表示一组响应
    
      @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    
        code：数字，例如400
    
        message：信息，例如"请求参数没填好"
    
        response：抛出异常的类
    
    @ApiModel：用于响应类上，表示一个返回响应数据的信息
    
          （这种一般用在post创建的时候，使用@RequestBody这样的场景，
    
          请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    
    @ApiModelProperty：用在属性上，描述响应类的属性

[http_localhost_content-path_swagger-ui_index.html]: http://localhost:8088/server/swagger-ui/index.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l5ajEwODMxNw_size_16_color_FFFFFF_t_70]: /images/20221120/348944049f624293b5e85cc1d8b8d9c7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l5ajEwODMxNw_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20201210231501181.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l5ajEwODMxNw==,size_16,color_FFFFFF,t_70