精华内容
下载资源
问答
  • Swagger2

    2021-03-17 21:21:43
    了解Swagger的作用和概念 了解前后端分离 在Springboot中集成Swagger Swagger 前后端分离 Vue+Springboot 后端时代:前端只用管前端静态页面;后端要htmk和jsp渲染数据。 前后端分离时代 后端:后端控制层,...

    注:看了狂神说自己所作的笔记  狂神说的笔记https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w

    学习目标

    • 了解Swagger的作用和概念
    • 了解前后端分离
    • 在Springboot中集成Swagger

     Swagger

    前后端分离

    Vue+Springboot

    后端时代:前端只用管前端静态页面;后端要htmk和jsp渲染数据。

    前后端分离时代

    • 后端:后端控制层,服务层,数据访问层
    • 前端:前端控制层,视图层   
    1. 伪造后端数据,json。已经存在了,不需要后端前端就可以单独运行
    • 前后端如何交互?===API
    • 前后端先对独立,松耦合
    • 前后端可以部署在不同的服务器

    产生了问题

    • 前后端联调,前后端无法做到“即使协商,尽早解决“,最终导致问题集中爆发.
    • 首先制定schema【计划的提纲】,实时更新最新的Api,降低集成风险;
    • 早期:制定word计划文档;
    • 前后端分离
    1. 前端测试后端接口:postman
    2. 后端提供接口,需要实时更新最新的消息改动

    Swagger

    • 世界上最流行的Api框架
    • RestFul Api 文档在线自动生成工具=API文档与API定义同步更新
    • 直接运行,可以在线测试API接口
    • 支持多种语言(java,php)

    在项目中使用springfox;

    • swagger2
    • ui

    SpringBoot集成Swagger2

    1.新建springboot项目

    2.pom导入swagger2的maven配置

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
    </dependency>
    ---------------------------------------------------------------------------------------
    	<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>2.10.5</version>
    		</dependency>
    
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>2.10.5</version>
    		</dependency>
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-spring-webmvc</artifactId>
    			<version>2.10.5</version>
    		</dependency>
    
    
    
    2.9.2  和  2.10.5 有差别的需要多导入一个jar 不然会报一个错
    @EnableSwagger2这个注解不能使用了 换成@EnableSwagger2WebMvc

    3.配置swagger配置文件

    @Configuration
    @EnableSwagger2WebMvc
    public class SwaggerConfig {
    }

    4.访问测试页面http://localhost:8080/swagger-ui.html

     

    配置Swagger

    1、Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2);
    }
    
    
    ----------------------------------------
    
    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    
    //配置文档信息
    private ApiInfo apiInfo() {
       Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
       return new ApiInfo(
               "Swagger学习", // 标题
               "学习演示如何配置Swagger", // 描述
               "v1.0", // 版本
               "http://terms.service.url/组织链接", // 组织链接
               contact, // 联系人信息
               "Apach 2.0 许可", // 许可
               "许可链接", // 许可连接
               new ArrayList<>()// 扩展
      );
    }

    配置扫描接口

    1、构建Docket时通过select()方法配置怎么扫描接口。

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
          .build();
    }
    
    --------------------------------------------------------
    any() // 扫描所有,项目中的所有接口都会被扫描到
    none() // 不扫描接口
    // 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
    withMethodAnnotation(final Class<? extends Annotation> annotation)
    // 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    withClassAnnotation(final Class<? extends Annotation> annotation)
    basePackage(final String basePackage) // 根据包路径扫描接口

    配置Swagger开关

    1、通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
    
    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }
    2、如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
    
    @Bean
    public Docket docket(Environment environment) {
       // 设置要显示swagger的环境
       Profiles of = Profiles.of("dev", "test");
       // 判断当前是否处于该环境
       // 通过 enable() 接收此参数判断是否要显示
       boolean b = environment.acceptsProfiles(of);
       
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }

    配置API分组

     

    1、如果没有配置分组,默认是default。通过groupName()方法即可配置分组
    @Bean
    public Docket docket(Environment environment) {
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
          .groupName("hello") // 配置分组
           // 省略配置....
    }
    2、重启项目查看分组
    
    3、如何配置多个分组?配置多个分组只需要配置多个docket即可:
    
    @Bean
    public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

    注解

    @Data
    @ApiModel("角色模型")
    public class Role {
        @ApiModelProperty("角色名称")
        private String rolename;
        @ApiModelProperty("用户ID")
        private String userId;
    }
    
    @RestController
    @Api(value="用户controller",tags={"用户操作接口"})
    public class HelloController {
        @ApiOperation("说你好")
        @GetMapping("hello")
        public Role sayHello(User user,@ApiParam("密码") String password,Role role)
        {
            User user1 = new User();
            user1.setAge("11");
            user1.setUsername("gene");
            return role;
        }
    }

    展开全文
  • SpringBoot集成Swagger2

    2021-01-10 16:39:25
    一、SpringBoot集成Swagger2 1.1、导入两个springfox的jar包 Springfox-Swagger2 Swagger-Springmvcs 二、使用Swagger 要求:jdk 1.8 + 否则Swagger2无法运行 步骤: 2.1、新建一个SpringBoot-web项目 2.2、...

    一、SpringBoot集成Swagger2

    1.1、导入两个springfox的jar包

    • Springfox-Swagger2
    • Swagger-Springmvcs

    二、使用Swagger

    要求:jdk 1.8 + 否则Swagger2无法运行

    步骤:

    2.1、新建一个SpringBoot-web项目

    2.2、添加Maven依赖

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger2</artifactId>
         <version>2.9.2</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.9.2</version>
    </dependency>
    

    2.3、编写HelloController,测试确保运行成功!

    2.4、要使用Swagger,我们需要编写一个配置类SwaggerConfig来配置 Swagger

    @Configuration //配置类
    @EnableSwagger2// 开启Swagger2的自动配置
    public class SwaggerConfig {  
    }
    

    2.5、访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面;

    在这里插入图片描述

    三、配置Swagger

    3.1、Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。

    @Configuration //定义Java配置类
    @EnableSwagger2 //开启Swagger2
    public class SwaggerConfig {
        @Bean //配置docket以配置Swagger具体参数
        public Docket docket() {
           return new Docket(DocumentationType.SWAGGER_2);
        }
    }
    

    3.2、可以通过apiInfo()属性配置文档信息

    //配置Swagger的apiInfo信息
        @Bean
        public ApiInfo apiInfo(){
            //作者信息
            Contact CONTACT = new Contact("未进化的程序猿", "https://www.cnblogs.com/the-undeveloped-procedural-ape/", "486566947@qq.com");
            return new ApiInfo("未进化的程序猿的Swagger日志", //Swagger文档标题
                               "Api Documentation",//Swagger文档描述
                               "v1.0",//Swagger文档版本号
                               "https://www.cnblogs.com/the-undeveloped-procedural-ape/",//博客地址
                               CONTACT,//作者信息
                               "Apache 2.0",
                               "http://www.apache.org/licenses/LICENSE-2.0",
                               new ArrayList());
        }
    

    3.3、Docket 实例关联上 apiInfo()

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    

    3.4、重启项目,访问测试 http://localhost:8080/swagger-ui.html;

    四、配置扫描接口

    4.1、构建Docket时通过select()方法配置怎么扫描接口。

    //往容器中注入一个Docket
        //配置了Swagger的Docket的Bean实例
        @Bean
        public Docket docket(Environment environment){
    
            //设置要显示的Swagger环境
            Profiles profiles = Profiles.of("dev","test");
    
            //获取项目的环境
            //通过environment.acceptsProfiles(profiles): 判断是否是自己设定的环境处于自己设定的环境当中
            boolean acceptsProfiles = environment.acceptsProfiles(profiles);
    
            return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo()) //Swagger的基本信息
                        .groupName("未进化的程序猿") //分组的名称
                        .enable(acceptsProfiles) //配置是否启用Swagger,如果是false,在浏览器将无法访问
                        .select() //配置Swagger扫描接口
                        //RequestHandlerSelectors配置Swagger扫描接口的方式
                        //basePackage("扫描的包路径")
                        //any(): 扫描全部
                        //none(): 都不扫描
                        //withClassAnnotation(Controller.class): 扫描类上的注解
                        //withMethodAnnotation(GetMapper.class): 扫描方法上的注解
                        .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                        //paths(): 过滤什么路径
                        //PathSelectors.ant("/"): 过滤要求
                        //.paths(PathSelectors.ant("/"))
                        .build();
        }
    

    4.2、重启项目测试,由于我们配置根据包的路径扫描接口,所以我们只能看到一个类

    4.3、除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式:

    any() // 扫描所有,项目中的所有接口都会被扫描到
    none() // 不扫描接口
    // 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
    withMethodAnnotation(final Class<? extends Annotation> annotation)
    // 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    withClassAnnotation(final Class<? extends Annotation> annotation)
    basePackage(final String basePackage) // 根据包路径扫描接口
    

    4.4、除此之外,我们还可以配置接口扫描过滤:

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }
    

    4.5、这里的可选值还有

    any() // 任何请求都扫描
    none() // 任何请求都不扫描
    regex(final String pathRegex) // 通过正则表达式控制
    ant(final String antPattern) // 通过ant()控制
    

    五、配置Swagger开关

    5.1、通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }
    

    5.2、如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?

    在这里插入图片描述

    application.properties

    在这里插入图片描述

    application-dev.properties

    在这里插入图片描述

    application-pro.properties

    在这里插入图片描述

    //往容器中注入一个Docket
        //配置了Swagger的Docket的Bean实例
        @Bean
        public Docket docket(Environment environment){
    
            //设置要显示的Swagger环境
            Profiles profiles = Profiles.of("dev","test");
    
            //获取项目的环境
            //通过environment.acceptsProfiles(profiles): 判断是否是自己设定的环境处于自己设定的环境当中
            boolean acceptsProfiles = environment.acceptsProfiles(profiles);
    
            return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo()) //Swagger的基本信息
                        .groupName("未进化的程序猿") //分组的名称
                        .enable(acceptsProfiles) //配置是否启用Swagger,如果是false,在浏览器将无法访问
                        .select() //配置Swagger扫描接口
                        //RequestHandlerSelectors配置Swagger扫描接口的方式
                        //basePackage("扫描的包路径")
                        //any(): 扫描全部
                        //none(): 都不扫描
                        //withClassAnnotation(Controller.class): 扫描类上的注解
                        //withMethodAnnotation(GetMapper.class): 扫描方法上的注解
                        .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                        //paths(): 过滤什么路径
                        //PathSelectors.ant("/"): 过滤要求
                        //.paths(PathSelectors.ant("/"))
                        .build();
        }
    

    5.3、可以在项目中增加一个dev的配置文件查看效果!

    在这里插入图片描述

    六、配置API分组

    在这里插入图片描述

    6.1、如果没有配置分组,默认是default。通过groupName()方法即可配置分组:

    @Bean
    public Docket docket(Environment environment) {
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
          .groupName("hello") // 配置分组
           // 省略配置....
    }
    

    6.2、重启项目查看分组
    6.3、如何配置多个分组?配置多个分组只需要配置多个docket即可:

    @Bean
    public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }
    

    6.4、重启项目查看即可

    七、实体配置

    7.1、新建一个实体类

    @ApiModel("用户实体")
    public class User {
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
    }
    

    7.2、只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中:

    @RequestMapping("/getUser")
    public User getUser(){
       return new User();
    }
    

    7.3、重启查看测试

    在这里插入图片描述

    注意:并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

    @ApiModel为类添加注释
    @ApiModelProperty为类属性添加注释

    八、常用注解

    Swagger的所有注解定义在io.swagger.annotations包下
    下面列一些经常用到的,未列举出来的可以另行查阅说明:

    在这里插入图片描述

    我们也可以给请求的接口配置一些注释

    @ApiOperation("未进化的程序猿的接口")
    @PostMapping("/kuang")
    @ResponseBody
    public String index(@ApiParam("这个名字会被返回")String username){
       return username;
    }
    

    九、SpringBoot集成Swagger 配置

    package com.example.springbootswagger.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.core.env.Environment;
    import org.springframework.core.env.Profiles;
    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;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    
    @Configuration //定义Java配置类
    @EnableSwagger2 //开启Swagger2
    public class SwaggerConfig {
    
        //创建多个组实例
        @Bean
        public Docket docket1(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("张三");
        }
    
        @Bean
        public Docket docket2(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
        }
    
        @Bean
        public Docket docket3(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("王五");
        }
    
        //往容器中注入一个Docket
        //配置了Swagger的Docket的Bean实例
        @Bean
        public Docket docket(Environment environment){
    
            //设置要显示的Swagger环境
            Profiles profiles = Profiles.of("dev","test");
    
            //获取项目的环境
            //通过environment.acceptsProfiles(profiles): 判断是否是自己设定的环境处于自己设定的环境当中
            boolean acceptsProfiles = environment.acceptsProfiles(profiles);
    
            return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo()) //Swagger的基本信息
                        .groupName("未进化的程序猿") //分组的名称
                        .enable(acceptsProfiles) //配置是否启用Swagger,如果是false,在浏览器将无法访问
                        .select() //配置Swagger扫描接口
                        //RequestHandlerSelectors配置Swagger扫描接口的方式
                        //basePackage("扫描的包路径")
                        //any(): 扫描全部
                        //none(): 都不扫描
                        //withClassAnnotation(Controller.class): 扫描类上的注解
                        //withMethodAnnotation(GetMapper.class): 扫描方法上的注解
                        .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                        //paths(): 过滤什么路径
                        //PathSelectors.ant("/"): 过滤要求
                        //.paths(PathSelectors.ant("/"))
                        .build();
        }
    
        //配置Swagger的apiInfo信息
        @Bean
        public ApiInfo apiInfo(){
            //作者信息
            Contact DEFAULT_CONTACT = new Contact("未进化的程序猿", "https://www.cnblogs.com/the-undeveloped-procedural-ape/", "486566947@qq.com");
            return new ApiInfo("未进化的程序猿的Swagger日志", //Swagger文档标题
                               "Api Documentation",//Swagger文档描述
                               "v1.0",//Swagger文档版本号
                               "https://www.cnblogs.com/the-undeveloped-procedural-ape/",//博客地址
                                DEFAULT_CONTACT,//作者信息
                               "Apache 2.0",
                               "http://www.apache.org/licenses/LICENSE-2.0",
                               new ArrayList());
        }
    
    }
    

    总结:

    1)、这样的话,可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读!

    2)、相较于传统的Postman或Curl方式测试接口,使用swagger简直就是傻瓜式操作,不需要额外说明文档(写得好本身就是文档)而且更不容易出错,只需要录入数据然后点击Execute,如果再配合自动化框架,可以说基本就不需要人为操作了。

    3)、Swagger是个优秀的工具,现在国内已经有很多的中小型互联网公司都在使用它,相较于传统的要先出Word接口文档再测试的方式,显然这样也更符合现在的快速迭代开发行情。当然了,提醒下大家在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时内存。

    展开全文
  • SpringBoot集成Swagger2与Swagger3的区别

    千次阅读 2021-04-14 10:41:10
    Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。...在SpringBoot中,Swagger2和Swagger3的集成方式有所不同,本文主要介绍SpringBoot集成Swagger2与Swagger3的区别。

    前言

    Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。


    一、pom文件中引入Swagger依赖

    Swagger2

    <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>
    

    Swagger3

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




    二、Swagger配置

    Swagger2

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    // 自行修改为自己的包路径
                    .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("swagger-api文档")
                    .description("swagger接入教程")
                    .version("1.0")
                    .contact(new Contact("TheTsing", "https://blog.csdn.net/qq_42375133?type=blog", "thetsing@foxmail.com"))
                    .build();
        }
    
    }
    

    Swagger3

    @Configuration
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                    .paths(PathSelectors.any())
                    .build()
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Api Documentation")
                    .contact(new Contact("TheTsing", "http://www.baidu.com", "thetsing@foxmail.com"))
                    .version("1.0")
                    .build();
        }
    
    }
    




    三、若配置有拦截器,应对Swagger做如下配置

    Swagger2

    @Configuration
    public class WebMvcConfig implements WebMvcConfigurer {
    
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
            // 配置swagger拦截器
            registry.addInterceptor(new MyInterceptor())// 这里加入自己写的拦截器
                    .addPathPatterns("/**").
                    excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**", "/v2/**");
        }
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 配置swagger静态资源映射
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    
        @Override
        public void addCorsMappings(CorsRegistry registry) {
            // 跨域支持
            registry.addMapping("/**").allowedOriginPatterns("*").allowedMethods("*").allowCredentials(true);
        }
    
    }
    

    Swagger3

    @Configuration
    public class WebMvcConfig implements WebMvcConfigurer {
    
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
            // 配置swagger拦截器
            registry.addInterceptor(new MyInterceptor())
                    .addPathPatterns("/**").
                    excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui/**", "/v3/**");
        }
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 配置swagger静态资源映射
            registry.addResourceHandler("/swagger-ui/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    
        @Override
        public void addCorsMappings(CorsRegistry registry) {
            // 跨域支持
            registry.addMapping("/**").allowedOriginPatterns("*").allowedMethods("*").allowCredentials(true);
        }
    
    }
    




    四、若项目中还有Token验证,则对应Swagger配置文件做如下修改

    Swagger2

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    // 自行修改为自己的包路径
                    .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                    .paths(PathSelectors.any())
                    .build()
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("swagger-api文档")
                    .description("swagger接入教程")
                    .version("1.0")
                    .contact(new Contact("TheTsing", "https://blog.csdn.net/qq_42375133?type=blog", "thetsing@foxmail.com"))
                    .build();
        }
    
        private List<ApiKey> securitySchemes() {
            List<ApiKey> apiKeyList = new ArrayList();
            apiKeyList.add(new ApiKey("token", "token", "header"));
            return apiKeyList;
        }
    
        private List<SecurityContext> securityContexts() {
            List<SecurityContext> securityContexts = new ArrayList<>();
            securityContexts.add(SecurityContext.builder()
                    .securityReferences(defaultAuth())
                    .forPaths(PathSelectors.regex("^(?!auth).*$"))
                    .build());
            return securityContexts;
        }
    
        List<SecurityReference> defaultAuth() {
            AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
            AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
            authorizationScopes[0] = authorizationScope;
            List<SecurityReference> securityReferences = new ArrayList<>();
            securityReferences.add(new SecurityReference("token", authorizationScopes));
            return securityReferences;
        }
    
    }
    

    Swagger3

    @Configuration
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.tsing"))
                    .paths(PathSelectors.any())
                    .build()
                    .protocols(newHashSet("https", "http"))
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Api Documentation")
                    .contact(new Contact("TheTsing", "http://www.baidu.com", "thetsing@foxmail.com"))
                    .version("1.0")
                    .build();
        }
    
        /**
         * 设置授权信息
         */
        private List<SecurityScheme> securitySchemes() {
            ApiKey apiKey = new ApiKey("token", "token", In.HEADER.toValue());
            return Collections.singletonList(apiKey);
        }
    
        /**
         * 授权信息全局应用
         */
        private List<SecurityContext> securityContexts() {
            return Collections.singletonList(
                    SecurityContext.builder()
                            .securityReferences(Collections.singletonList(new SecurityReference("token", new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")})))
                            .build()
            );
        }
    
        @SafeVarargs
        private final <T> Set<T> newHashSet(T... ts) {
            if (ts.length > 0) {
                return new LinkedHashSet<>(Arrays.asList(ts));
            }
            return null;
        }
    
    }
    




    五、访问路径

    Swagger2和Swagger3的访问路径也有所不同

    Swagger2:http://localhost:port/swagger-ui.html
    Swagger3:http://localhost:port/swagger-ui/index.html


    总结

    如果这篇博客对你有帮助的话,记得给我点个赞,你的鼓励是对我最大的支持!谢谢。◕‿◕。
    展开全文
  • Spring Boot集成Swagger2

    2021-01-14 15:18:21
    前言:目前互联网开发市场都流行前后台...今天就介绍一款将接口文档编写和测试合并一起的集大成者Swagger,也是目前很多企业再用的一个API管理工具。此DEMO的开发环境是:MAVEN + Spring Boot 2.1.0 + JDK8 + Swa...

    前言:目前互联网开发市场都流行前后台真正的分离,后台提供数据API接口,前台负责请求数据并渲染。那么我们程序猿们在编写接口的时候,最不方便之处就是写完接口后需要进行文档的编写以及接口的测试。今天就介绍一款将接口文档编写和测试合并一起的集大成者Swagger,也是目前很多企业再用的一个API管理工具。此DEMO的开发环境是:MAVEN + Spring Boot 2.1.0 + JDK8 + Swagger2.9.2

    1、快速构建Spring Boot项目

    在https://start.spring.io/中选择Maven构建Java项目,然后选用Spring Boot2.1.0版本,Group是com.mage,Artifact是swagger_restful,Dependencies选择web,这样就能快速构建一个基于Spring Boot的web项目了。如下图:

    2、使用IDEA打开项目

    解压swagger_restful.zip,然后使用idea导入项目,并执行SwaggerRestfulApplication.java,不报错说明项目构建成功

    3、pom导入swagger2的依赖jar包

    io.springfox

    springfox-swagger2

    2.9.2

    io.springfox

    springfox-swagger-ui

    2.9.2

    5、编写测试的Controller和Model(TestController和Test)

    编写一个Test的数据模型

    package com.mage.swagger_restful.model;

    public class Test {

    private Integer id;

    private String content;

    private Integer isValid;

    public Integer getId() {

    return id;

    }

    public void setId(Integer id) {

    this.id = id;

    }

    public String getContent() {

    return content;

    }

    public void setContent(String content) {

    this.content = content;

    }

    public Integer getIsValid() {

    return isValid;

    }

    public void setIsValid(Integer isValid) {

    this.isValid = isValid;

    }

    }

    基于Restful规则,编写一组测试的API接口:

    package com.mage.swagger_restful.controller;

    import org.springframework.web.bind.annotation.*;

    @RestController

    @RequestMapping("test")

    public class TestController {

    @GetMapping("")

    public String list() {

    return "查询列表数据!";

    }

    @GetMapping("{id}")

    public String find(@PathVariable Integer id) {

    return String.format("根据主键查询数据: %d", id);

    }

    @PostMapping("")

    public String add() {

    return "插入数据!";

    }

    @PutMapping("{id}")

    public String update(@PathVariable Integer id) {

    return String.format("根据主键更新一条记录: %d", id);

    }

    @DeleteMapping("{id}")

    public String delete(@PathVariable Integer id) {

    return String.format("根据主键删除记录: %d", id);

    }

    }

    因为接口是基于Restful(本文不讨论Restful的编写规范)编写,所以如果单纯利用浏览器输入是没法进行接口测试的,比如模拟post, put或者delete请求,这时要测试可以借助一些浏览器的插件比如postman或者rested等。这样我们还要额外去安装工具,显得比较麻烦,同时工作中写完接口后,一般还会编写接口文档,那么聪明的码农就想着能不能优化这个流程,让接口测试和接口文档编写变得简单快捷,于是乎,swagger应用而生。

    6、代码中集成Swagger

    a) 编写Swagger的配置类

    package com.mage.swagger_restful.config;

    import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;

    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.spi.DocumentationType;

    import springfox.documentation.spring.web.plugins.Docket;

    import springfox.documentation.swagger2.annotations.EnableSwagger2;

    @Configuration

    @EnableSwagger2

    @ConditionalOnExpression("${swagger.enable:true}")

    public class SwaggerConfig {

    @Bean

    public Docket createDocket(){

    Docket docket = new Docket(DocumentationType.SWAGGER_2)

    .apiInfo(new ApiInfoBuilder().title("码歌学院API")

    .description("码歌学院相关接口API文档")

    .version("1.0").build())

    .select()

    .apis(RequestHandlerSelectors.basePackage("com.mage"))

    .paths(PathSelectors.any())

    .build();

    return docket;

    }

    }

    其中@EnableSwagger2开启Swagger2功能,是swagger2的注解,@ConditionalOnExpression("${swagger.enable:true}")当配置文件中swagger.enable为true时才启用swagger2,是spring boot注解,方便区分不同环境下是否启用swagger2。

    b) 修改application.properties

    swagger.enable=true

    c) 修改Test实体模型和TestController,添加Swagger对应注解

    修改Test实体模型:

    package com.mage.swagger_restful.model;

    import io.swagger.annotations.ApiModel;

    import io.swagger.annotations.ApiModelProperty;

    @ApiModel(description = "测试模型实体")

    public class Test {

    @ApiModelProperty(name = "id", value = "主键", hidden = true)

    private Integer id;

    @ApiModelProperty(name = "content", value = "测试内容")

    private String content;

    @ApiModelProperty(name = "isValid", value = "是否有效0=无效,1=有效", hidden = true)

    private Integer isValid;

    public Integer getId() {

    return id;

    }

    public void setId(Integer id) {

    this.id = id;

    }

    public String getContent() {

    return content;

    }

    public void setContent(String content) {

    this.content = content;

    }

    public Integer getIsValid() {

    return isValid;

    }

    public void setIsValid(Integer isValid) {

    this.isValid = isValid;

    }

    }

    其中:

    @ApiModel(description = "测试模型实体")作用在参数实体或者响应实体上,description代表描述信息;

    @ApiModelProperty(name = "id", value = "主键", hidden = true)作用在实体属性上,标记属性名称和说明内容,name代表属性名称,value表示属性内容,hidden是否因此,默认是false。

    修改TestController:

    package com.mage.swagger_restful.controller;

    import com.mage.swagger_restful.model.Test;

    import io.swagger.annotations.Api;

    import io.swagger.annotations.ApiImplicitParam;

    import io.swagger.annotations.ApiOperation;

    import io.swagger.annotations.ApiParam;

    import org.springframework.web.bind.annotation.*;

    @RestController

    @RequestMapping("test")

    @Api(tags = "测试API接口")

    public class TestController {

    @GetMapping("")

    @ApiOperation(value="获取列表数据", notes="获取列表下测试数据")

    public String list() {

    return "查询列表数据!";

    }

    @GetMapping("{id}")

    @ApiOperation(value="获取ID数据", notes="根据ID获取某条测试数据")

    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)

    public String find(@PathVariable Integer id) {

    return String.format("根据主键查询数据: %d", id);

    }

    @PostMapping("")

    @ApiOperation(value="新增数据")

    @ApiParam(name = "test", value = "添加的测试模型实体")

    public String add(@RequestBody Test test) {

    return "插入数据!";

    }

    @PutMapping("{id}")

    @ApiOperation(value="更新数据", notes="根据ID更新测试数据")

    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)

    public String update(@PathVariable Integer id, @ApiParam(name = "test", value = "更新的测试模型实体") @RequestBody Test test) {

    return String.format("根据主键更新一条记录: %d", id);

    }

    @DeleteMapping("{id}")

    @ApiOperation(value="删除数据", notes="根据ID删除测试数据")

    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)

    public String delete(@PathVariable Integer id) {

    return String.format("根据主键删除记录: %d", id);

    }

    }

    其中:

    @Api(tags = "测试API接口")标记controller类是做什么的,tags表示分类;

    @ApiOperation(value="获取列表数据", notes="获取列表下测试数据")标记controller下的方法,表示这个接口是做什么的,value就是说明作用,notes详细说明;

    @ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)标记参数,name是参数名,value是参数说明,paramType是参数类型:path(路径参数),query(查询参数), body(请求体参数),header(请求头参数),form(表单提交参数),require代表是否必填,默认是false

    @ApiParam(name = "test", value = "更新的测试模型实体")跟@ApiImplicitParam类似,标记参数,不过不同的是:对Servlets或者非 JAX-RS的环境,只能使用 ApiImplicitParam。

    在使用上,ApiImplicitParam比ApiParam具有更少的代码侵入性,只要写在方法上就可以了,但是需要提供具体的属性才能配合swagger ui解析使用。

    ApiParam只需要较少的属性,与swagger ui配合更好。

    点开测试API接口就可以进行测试:

    8、注意

    如果采用swagger2.9.0时,会出现一个bug,比如我修改一下TestController里面的find方法

    旧方法:

    新方法:

    这时如果启动,访问swagger ui时会出现一个bug:

    这个是一个数据类型转化的错误,就是因为我设置了id为int类型,而swagger默认给的是空字符串,因此就提示错误,解决方案有两种,第一种就是不要写dataType,第二种就是升级swagger-annotations和models jar包:

    a)排除已经依赖的swagger-annotations和models jar包

    io.springfox

    springfox-swagger2

    2.9.2

    io.swagger

    swagger-annotations

    io.swagger

    swagger-models

    b) 引入新的jar包

    io.swagger

    swagger-annotations

    1.5.21

    io.swagger

    swagger-models

    1.5.21

    这样也能完美解决!

    展开全文
  • SpringBoot整合Swagger2

    2021-07-15 13:53:10
    前后端分离后,维护...还好,有一些工具可以减轻我们的工作量,Swagger2就是其中之一,至于其他类似功能但是却收费的软件,这里就不做过多介绍了。本文主要和大伙来聊下在Spring Boot中如何整合Swagger2。 1、Swagge
  • Swagger的使用,包括swagger2和swagger3

    千次阅读 2021-08-20 13:25:09
    Swagger的使用 1、建一个maven项目 2、引入依赖 <dependency> <groupId>io.springfox<...springfox-swagger2</artifactId> <version>2.7.0</version> </dependency>
  • Swagger2配置

    2021-03-10 16:09:47
    要求:jdk 1.8 + 否则swagger2无法运行 1.创建一个springBoot web项目 2.添加依赖库 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io....
  • Swagger-Swagger2配置依赖引入详细配置swagger资源访问路径加入白名单访问路径:小技巧: 相关内容 地址 Swagger官方文档 https://swagger.io/docs/specification/2-0/basic-structure/ Swagger2常用注解...
  • swagger使用指南
  • swagger2

    2021-10-25 19:53:09
    文章目录 swagger2 简介 使用 导包 编写配置类 配置基本显示的信息 配置扫描接口 配置是否开启 开发环境关闭,测试环境开启 分组 文档中的models 给swagger-ui文档添加注释 swagger2 皆来自“狂神说Java” swagger3...
  • 1,配置 2,注解 3,切换主题 4,生成pdf文件,解决中文丢失 adoc-html-pdf github
  • Swagger2接口测试

    2021-08-27 14:57:15
    创建一个 Spring Boot 工程,加入 web 依赖,工程创建成功后,加入 Swagger2 相关依赖(springfox-swagger2、springfox-swagger-ui)。 Maven 仓库地址:https://mvnrepository.com/ 1、导入依赖 <dependency>...
  • pringfox-swagger2依然是依赖OSA规范文档,也就是一个描述API的json文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更...
  • spring cloud gateway 集成swaggwr2前言集成1、maven依赖2、配置Swagger Config3、开发遇到的问题1、不能推断出base URL可能由以下几个原因造成: 前言 我们都知道springcloud的gateway没有采用传统的阻塞式的...
  • swagger2当中在简单java类属性上添加ApiModelProperty用于扩展前端文档的显示功能,比如如下配置如下 @ApiModelProperty(value = "外部资金账号id", required = true, position = 1) 前两个属性value和required没...
  • 1. 什么是Swgger 号称世界上最流行的API框架 Restful Api 文档在线自动生成器 =>...2. SpringBoot集成Swagger2 2.1 引入依赖 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
  • swagger2技术

    2021-01-17 12:41:11
    1.什么是Swagger2?Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以...
  • SpringBoot+Swagger2

    2021-02-26 17:16:18
    SpringBoot+Swagger2一、小于3.0.0版本1.增加jar在pom.xml2.创建Swagger2配置类3.创建Controller类4.访问路径二、大于3.0.0版本(包含3.0)1.增加jar在pom.xml2.创建Swagger2配置类3.创建Controller类4.访问路径 ...
  • Swagger2 和 Swagger3 的区别与使用 主要区别: 1 导入的依赖 注意:我springboot 使用的版本为4.3.1, 版本过高会报错 Swagger2 <dependency> <groupId>io.springfox</groupId> <artifactId&...
  • 在目前前后端分离的模式中无论是前端开发还是后端开发基本上都被文档折磨过,前端开发经常会遇到后端接口改变,调整等文档未及时更新问题,...解决方案多了就行成了标准,这就是Swagger的由来。 根据官网的介绍,Swagg.
  • mybatisplus+swagger2

    2021-05-30 23:02:19
    pom.xml 引入如下包 ... } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger2构建api文档") .description("简单优雅的restful风格") .version("1.0") .build(); } }
  • swagger2 入门教程

    2021-02-28 09:45:21
    swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它作用:1、接口的文档在线自动生成2、功能测试先介绍它的常用注解@Api 注解可以用来标记 ...
  • swagger2的详细笔记

    2021-01-20 21:58:43
    Swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务。 接口文档对于前后端开发人员都非常重要。Swagger可以使得接口文档动态生成 OpenApi:是REST API的api描述格式 每个访问地址...
  • 配置 Swagger2 接口文档引擎

    千次阅读 2020-12-31 13:00:37
    本节视频手写文档存在的问题文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。接口返回结果不明确不能直接在线测试接口,通常需要使用工具,比如:Postman...Maven增加 Swagger2 所需依赖,...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 93,091
精华内容 37,236
关键字:

swagger2

友情链接: ACO.zip