Spirng Boot-Swagger

最新推荐文章于 2024-09-15 15:14:28 发布

韩雨泽_97

最新推荐文章于 2024-09-15 15:14:28 发布

阅读量354

点赞数

分类专栏： spring boot学习记录文章标签： spring boot

本文链接：https://blog.csdn.net/qq_43572551/article/details/106600028

版权

spring boot学习记录专栏收录该内容

18 篇文章 0 订阅

订阅专栏

一、学习目标

了解Swagger的概念及作用
掌握在项目中集成Swagger自动生成API文档

二、Swagger简介

前后端分离

前端 > 前端控制器、视图层
后端 > 后端控制器、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合

产生的问题

前后端集成，前端后者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

首先定义schema[计划的提纲]，并实时跟踪最新的API，降低集成风险

Swagger

世界上最流行的API框架
Resultful Api 文档在线自动生成器 => API文档与API定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）

三、SpringBoot集成Swagger

Springboot集成Swagger => Springfox，两个jar包

Springfox-swagger2
swagger-springmvc

使用Swagger

要求：jdk1.8以上，否则swagger2无法运行

四、案例

新建一个SpringBoot项目（选择web模块即可）
添加maven依赖

 <!-- swagger依赖 -->
        <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>

编写HelloController，测试确保运行成功!

/**
 * @author hyz
 * @create 2020-06-06 14:36
 */
@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

编写Swagger配置类（SwaagerConfig）

/**
 * @author hyz
 * @create 2020-06-06 14:41
 * swagger配置类
 */
@Configuration
//开启swagger2
@EnableSwagger2
public class SwaggerConfig {
}

访问测试:http://localhost:8080/swagger-ui.html,即可看到Swagger的界面

该界面主要分为四块区域，如下图所示：

五、配置Swagger

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger

  //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docker(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2);
    }

通过apiInfo()来属性配置文档信息

  @Bean
    public Docket docker(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2);
    }
    
 //配置Swagger信息 = apiInfo
    public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("韩雨泽","http://www.hanyuze.top/","xxx@163.com");
        return new ApiInfo(
                "韩雨泽的SwaggerAPI文档", //标题
                "帅气的小伙子", //描述
                "v1.0", //版本
                "http://www.hanyuze.top/", //组织链接
                contact, //联系人信息
                "Apache 2.0", //许可
                "http://www.apache.org/licenses/LICENSE-2.0", //许可链接
                new ArrayList()); //扩展
    }

Docket实例关联上apiInfo()

 @Bean
    public Docket docker(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo();
    }
    
 //配置Swagger信息 = apiInfo
    public ApiInfo apiInfo(){
        //作者信息
        //Contact contact = new Contact("联系人名字","联系人访问链接","联系人邮箱");
        Contact contact = new Contact("韩雨泽","http://www.hanyuze.top/","xxx@163.com");
        return new ApiInfo(
                "韩雨泽的SwaggerAPI文档", //标题
                "帅气的小伙子", //描述
                "v1.0", //版本
                "http://www.hanyuze.top/", //组织链接
                contact, //联系人信息
                "Apache 2.0", //许可
                "http://www.apache.org/licenses/LICENSE-2.0", //许可链接
                new ArrayList()); //扩展
    }

重启项目，访问测试 http://localhost:8080/swagger-ui.html

六、配置扫描接口

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

 @Bean
    public Docket docker(Environment environment){
       return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("韩雨泽")
                //通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .select()
               //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage 根据包路径扫描接口
                //any():扫描全部，项目中所有接口都会被扫描到
                //none():不扫描接口
                //withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))
                .build();
    }

重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
还可以配置接口扫描过滤

 @Bean
    public Docket docker(Environment environment){
       return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .select()
                .groupName("韩雨泽")
               //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage 根据包路径扫描接口
                //any():扫描全部，项目中所有接口都会被扫描到
                //none():不扫描接口
                //withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))
                //过滤路径,例如这里只扫描请求以/admin开头的接口
                //any():任何接请求都扫描
                //none():任何请求都不扫描
                //regex():通过正则表达式控制
                //ant():通过ant()控制
                .paths(PathSelectors.ant("/admin/**"))
                .build();
    }

七、配置Swagger开关

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

 @Bean
    public Docket docker(Environment environment){
       return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("韩雨泽")
                //是否启用Swagger,如果为false,则不能在浏览器访问
                .enable(false)
                //通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .select()
               //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage 根据包路径扫描接口
                //any():扫描全部，项目中所有接口都会被扫描到
                //none():不扫描接口
                //withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))
                //过滤路径,例如这里只扫描请求以/admin开头的接口
                //any():任何接请求都扫描
                //none():任何请求都不扫描
                //regex():通过正则表达式控制
                //ant():通过ant()控制
                .paths(PathSelectors.ant("/admin/**"))
                .build();
    }

如何动态配置当项目处于开发环境(dev)环境时显示,生产环境(pro)不显示？

    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docker(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","pro");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("韩雨泽")
                //是否启用Swagger,如果为false,则不能在浏览器访问
                .enable(flag)
                //通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage 根据包路径扫描接口 
                //any():扫描全部，项目中所有接口都会被扫描到
                //none():不扫描接口
                //withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))
                //过滤路径,例如这里只扫描请求以/admin开头的接口
                //any():任何接请求都扫描
                //none():任何请求都不扫描
                //regex():通过正则表达式控制
                //ant():通过ant()控制
//                .paths(PathSelectors.ant("/admin/**"))
                .build();
    }

八、配置API分组

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

    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docker(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("韩雨泽") //配置分组
                //省略配置......
                .build();
    }

重启项目查看分组
如何配置多个分组？
配置多个分组只需要配置多个Docket即可

 //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docker(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("1") //配置分组
                //省略配置......
                .build();
    }
     //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docker(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("2") //配置分组
                //省略配置......
                .build();
    }
     //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docker(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("3") //配置分组
                //省略配置......
                .build();
    }

4.重启项目查看即可

九、实体配置

新建一个实体类

/**
 * @author hyz
 * @create 2020-06-06 16:00
 */
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

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

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

3.重启项目查看
在这里插入图片描述
注意：
并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@AapiModelProperty这两个注解是为实体添加注释的。

@ApiModel：为实体类添加注释
@AapiModelProperty：为实体类属性添加注释

更多注解请查看官网手册

十、扩展：网页皮肤

我们可以导入不同的包实现不同的皮肤定义:
1.默认的(访问http://localhost:8080/swagger-ui.html)

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

2.bootstrap-ui(访问http://localhost:8080/doc.html)

 <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>

3.Layui-ui(访问http://localhost:8080/docs.html)

 <dependency>
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-lalyer</artifactId>
            <version>1.1.3</version>
        </dependency>

4.mg-ui(访问http://localhost:8080/document.html)

 <dependency>
            <groupId>com.zyplayer</groupId>
            <artifactId>swagger-mg-ui</artifactId>
            <version>1.0.6</version>
        </dependency>