SpringBoot集成Swagger

清疚 2024-03-26 00:01 128阅读 0赞

> [Java知识点总结：想看的可以从这里进入][Java]

#### 目录 ####

*   *   *  2.17、Swagger
         *   *  2.17.1、简介
             *  2.17.2、常用注解
             *  2.17.3、Swagger2集成
             *  2.17.4、Swagger3集成

#### 2.17、Swagger ####

##### 2.17.1、简介 #####

现在的编程从后端时代向逐渐编程后端分离的时代，前后端通过API接口进行交互，前后端相对独立，于是Swagger就产生了，它是一个简单但功能强大的API表达工具，号称最流行的API框架。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

[Swagger官网][Swagger]

Vue+Springboot 是现今主流的前后端分离的方案。

##### 2.17.2、常用注解 #####

Swagger提供的注解是用在Controller、实例类上对接口的和实体类的属性进行说明，这些说明可以显示在Swagger 的操作页面上，帮助我们理解使用。

1.  @Api(tags=“Restful风格测试”)：用在controller类上，标记一个controller类为swagger的文档资源
    
    属性：tags=“说明该类的作用，可以在UI界面上看到的注解” value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
    
    ![image-20210908180201905][]
2.  @ApiModel(value = “User实体类”,description =“存放用户的数据” )：用在实体类上，对类进行说明
    
    ![image-20210908180532117][]
3.  @ApiModelProperty(value=“描述信息”)：用在属性上，描述属性的作用
    
    ![image-20210908180907084][]
4.  @ApiParam(value=“描述”,required = true)：用在controller方法的参数前，描述该参数的作用，required 为true是表示该参数必须传递
    
    ![image-20210908181140793][]
5.  @ApiOperation(value = ")：用在controller方法上，描述该方法的作用
    
    value=“说明方法的用途、作用” notes=“方法的备注说明”
    
    ![image-20210908181607635][]
6.  @ApiResponses：用在controller的方法上，描述接口相应的相关信息
    
        @ApiResponses({
              
                @ApiResponse(code = 0,message = "相应成功",response = User.class),
                @ApiResponse(code = 状态码,message = "结果",response = 操作的对象)
        })
    
    ![image-20210908182055570][]
7.  @ApiImplicitParams：用在方法，用于描述方法内的参数的信息，可以设置默认值
    
        @ApiImplicitParams({
              
                @ApiImplicitParam(name = "id",value = "用户的id",dataType = "int" ,
                        paramType = "用于查询",required = true,defaultValue = "1"),
            	@ApiImplicitParam(name = "参数名",value = "作用",dataType = "数据类型" 
                        paramType = "用于什么操作",required = 是否必须传递,defaultValue = "默认值"),
        })

##### 2.17.3、Swagger2集成 #####

1.  导入pom依赖 springfox-swagger2、springfox-swagger-ui
    
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
2.  在配置文件中添加：（SpringBoot2.6及其以上版本启动swagger2.9.2会保错，所有需要添加一下配置）
    
        spring:  
          mvc:
            pathmatch:
              matching-strategy: ANT_PATH_MATCHER
3.  配置swagger的config 配置类
    
        @Configuration
        @EnableSwagger2		//swagger2注解
        public class Swagger2Config {
              
        //配置swagger
            @Bean
            public Docket docket(Environment environment){
              
                //获取当前的环境配置
                Profiles profiles = Profiles.of("dev");
                //通过环境变量判断是否符合需要的环境
                boolean b = environment.acceptsProfiles(profiles);
                log.info("当前的环境：{}",b);
                
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())     //配置信息
                        .select()
                            //扫描接口的方式：basePackage(根据包),any(扫描全部),none(都不扫描),
                            // withClassAnnotation(扫描类上的注解),withMethodAnnotation(方法上的注解)
                            .apis(RequestHandlerSelectors.basePackage("com.yu.springbootdemo.controller"))
                            //对指定的路径进行监视：PathSelectors.any()所有的，none()都不监视，ant(final String antPattern):匹配Ant样式的路径模式
                    		 .paths(PathSelectors.any())
                        .build()     //添加select内的配置，select的结束
                        .enable(b)   //是否开启swagger,根据开发环境判断是否开启
                        .groupName("A")   //配置一个分组，多人开发，有多个docket，通过分组查找个人的
                        ;
            }
        
            //配置swagger基础信息，apiInfo
            //(title,description,version,termsOfServiceUrl,contact,license,licenseUrl)
            public ApiInfo  apiInfo(){
              
                //作者信息
                Contact contact = new Contact("","","");
                return new ApiInfoBuilder()
                        .title("标题：测试swagger")      //title标题
                        .description("测试文档")     //description描述
                        .version("1.0")          //version版本
                        .termsOfServiceUrl("aaaa")     //服务路径
                        .contact(contact)           //contact 作者信息
                        .license("Apache 2.0")      //许可证
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")   //许可证路径
                        .build();
            }
        }
4.  如果配置了shiro、SpringSecurity等权限框架，需要在安全框架内部对swagger的一些默认路径放行
    
        //swagger2放行
        filterMap.put("/swagger-ui.html", "anon");
        filterMap.put("/swagger-resources", "anon");
        filterMap.put("/swagger-resources/configuration/security", "anon");
        filterMap.put("/swagger-resources/configuration/ui", "anon");
        filterMap.put("/v2/api-docs", "anon");
        filterMap.put("/webjars/springfox-swagger-ui/**", "anon");
    
        .antMatchers("/swagger-ui.html").permitAll()
            .antMatchers("/swagger-resources/**").permitAll()
            .antMatchers("/webjars/**").permitAll()
            .antMatchers("/v2/api-docs").permitAll()
5.  如果配置了WebMvcConfigurer，也需要对swagger路径进行放行
    
        @Configuration
        public class WebMvcConfigure implements WebMvcConfigurer {
              
        
            @Override
            public void addResourceHandlers(ResourceHandlerRegistry registry) {
              
                registry.addResourceHandler("/static/**").addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/static/");
                registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
                registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
            }
        }
6.  编写Controller 进行测试
    
        @Api(tags = "swagger测试")
        @Controller
        public class PageController {
              
            @ApiOperation(value = "hello测试", notes = "访问此接口返回hello springboot ")
            @PostMapping("/hello")
            @ResponseBody
            public String hello(){
              
                return "hello springboot";
            }
        }
7.  访问 http://localhost:8080/swagger-ui.html
    
    ![image-20221006165346106][]
    
    ![image-20221006165406508][]
    
    ![image-20221006165653232][]

##### 2.17.4、Swagger3集成 #####

Swagger3在 2 的基础上做了很大的升级，但使用的方式差别不大，只是其中有些配置不同

<table> 
 <thead> 
  <tr> 
   <th>区别</th> 
   <th>swagger2</th> 
   <th>swagger3</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>依赖</td> 
   <td>springfox-swagger2、springfox-swagger-ui</td> 
   <td>springfox-boot-starter</td> 
  </tr> 
  <tr> 
   <td>启动注解</td> 
   <td>@EnableSwagger2</td> 
   <td>@EnableOpenApi</td> 
  </tr> 
  <tr> 
   <td>Document类型</td> 
   <td>DocumentationType.SWAGGER_2</td> 
   <td>DocumentationType.OAS_30</td> 
  </tr> 
  <tr> 
   <td>网址</td> 
   <td>http://ip:port/{context-path}/swagger-ui.html</td> 
   <td>http://ip:port/{context-path}/swagger-ui/index.html</td> 
  </tr> 
 </tbody> 
</table>

1.  导入pom依赖 （）
    
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
2.  在配置文件中添加：防止版本问题启动失败
    
        spring:  
          mvc:
            pathmatch:
              matching-strategy: ANT_PATH_MATCHER
3.  配置swagger的config 配置类
    
        @Configuration
        @EnableOpenApi		//swagger3注解
        public class Swagger2Config {
              
        //配置swagger
            @Bean
            public Docket docket(Environment environment){
              
                //获取当前的环境配置
                Profiles profiles = Profiles.of("dev");
                //通过环境变量判断是否符合需要的环境
                boolean b = environment.acceptsProfiles(profiles);
                log.info("当前的环境：{}",b);
                //DocumentationType.SWAGGER_2 改为 DocumentationType.OAS_30
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())     //配置信息
                        .select()
                            //扫描接口的方式：basePackage(根据包),any(扫描全部),none(都不扫描),
                            // withClassAnnotation(扫描类上的注解),withMethodAnnotation(方法上的注解)
                            .apis(RequestHandlerSelectors.basePackage("com.yu.springbootdemo.controller"))
                            //对指定的路径进行监视：PathSelectors.any()所有的，none()都不监视，ant(final String antPattern):匹配Ant样式的路径模式
                    		 .paths(PathSelectors.any())
                        .build()     //添加select内的配置，select的结束
                        .enable(b)   //是否开启swagger,根据开发环境判断是否开启
                        .groupName("A")   //配置一个分组，多人开发，有多个docket，通过分组查找个人的
                        ;
            }
        
            //配置swagger基础信息，apiInfo
            //(title,description,version,termsOfServiceUrl,contact,license,licenseUrl)
            public ApiInfo  apiInfo(){
              
                //作者信息
                Contact contact = new Contact("","","");
                return new ApiInfoBuilder()
                        .title("标题：测试swagger3")      //title标题
                        .description("测试文档")     //description描述
                        .version("1.0")          //version版本
                        .termsOfServiceUrl("aaaa")     //服务路径
                        .contact(contact)           //contact 作者信息
                        .license("Apache 2.0")      //许可证
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")   //许可证路径
                        .build();
            }
        }
4.  如果配置了shiro、SpringSecurity等权限框架，需要在安全框架内部对swagger3 的一些默认路径放行
    
        //swagger2放行
        filterMap.put("/swagger-ui/index.html", "anon");
        filterMap.put("/swagger-resources", "anon");
        filterMap.put("/swagger-resources/configuration/security", "anon");
        filterMap.put("/swagger-resources/configuration/ui", "anon");
        filterMap.put("/v2/api-docs", "anon");
        filterMap.put("/webjars/springfox-swagger-ui/**", "anon");
    
        .antMatchers("/swagger-ui/index.html").permitAll()
            .antMatchers("/swagger-resources/**").permitAll()
            .antMatchers("/webjars/**").permitAll()
            .antMatchers("/v2/api-docs").permitAll()
5.  如果配置了WebMvcConfigurer，也需要对swagger3 路径进行放行
    
        @Configuration
        public class WebMvcConfigure implements WebMvcConfigurer {
              
        
            @Override
            public void addResourceHandlers(ResourceHandlerRegistry registry) {
              
                registry.addResourceHandler("/static/**").addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/static/");
                registry.addResourceHandler("swagger-ui/index.html").addResourceLocations("classpath:/META-INF/resources/");
                registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
            }
        }
6.  编写Controller 进行测试
    
        @Api(tags = "swagger3测试")
        @Controller
        @RequestMapping("/restfulTest")
        public class RestfulTestController {
              
        
            @Resource
            private UserinfoService userinfoService;
        
        
            @ApiOperation(value = "获取用户信息", notes = "访问此接口返回userinfo信息")
            @GetMapping("/getUserinfo/{id}")
            @ResponseBody
            public Userinfo getUserinfo(@PathVariable("id")long id){
              
                return userinfoService.getById(id);
            }
        
        
        }
7.  访问 http://localhost:8080/swagger-ui/index.html
    
    ![image-20230309205444594][] ![image-20230309205529654][] ![image-20230309205607795][]

[Java]: https://blog.csdn.net/yuandfeng/article/details/114333525
[Swagger]: https://swagger.io/
[image-20210908180201905]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/94f07c1db7134811af61a23ffebeacdf.png
[image-20210908180532117]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/d3408ddf21df47bca9edd49abe34ddb7.png
[image-20210908180907084]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/442f2a2f11de4384a75c1cdfcdb5ae3b.png
[image-20210908181140793]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/0670f8388d214b42b65794c50717fd02.png
[image-20210908181607635]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/30a792477c8c45fabd2eaa196b10ecd4.png
[image-20210908182055570]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/6066f35a64be4cbcb51b8a726d24e555.png
[image-20221006165346106]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/822b0fdc17504affaca7e4883435b578.png
[image-20221006165406508]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/88fdaa7bb44842858fd92463fe1ccc2a.png
[image-20221006165653232]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/a1b171902fed48c7bc3da7082bf37058.png
[image-20230309205444594]: https://yudejava.oss-cn-hangzhou.aliyuncs.com/typora/202303231122534.png
[image-20230309205529654]: https://yudejava.oss-cn-hangzhou.aliyuncs.com/typora/202303231122525.png
[image-20230309205607795]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/25/256d1c36f26e4652aa9e7a69f6615d9e.png