Springboot集成Swagger

        <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.9.2</version>
        </dependency>
<!--    web环境-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.3.7.RELEASE</version>
        </dependency>

如果适用2.7.0还会有错误，建议降低springboot版本号到2.5.0


    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

2.2 配置类（Springboot集成）

swagger-ui.html访问不到404,那就降低我们刚刚两个左边的版本，比如改成2.7.0（两个依赖都要改）

如果在启动时出现了其他的方法，也可以尝试将依赖的版本降低一些

@EnableSwagger2注解的作用是启用Swagger2自动生成API文档并提供可视化的界面，方便开发人员查看和测试API

下面的这段代码是使用的默认的swagger配置


@Configuration   //加入到容器里面
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {


}

2.3 启动并访问

Swagger UI

下面是效果图

2.4 配置Swagger

Swagger的bean实例Docket

2.4.1 Swagger的bean实例Docket


@Configuration   //加入到容器里面
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {

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

2.4.1.1源码解析DocumentationType.SWAGGER_2含义

这个地方为什么传一个他呀？

我们看一下Docket构造器，发现传入DocumentationType类型的参数

我们查看一下DocumentationType类

我们再看一下这些字段，很明显我们是2.0版本，故传入DocumentationType.SWAGGER_2

另外插一句话

在我们还没有配置之前，我们可以先点进这个Docket类中看一下，有一个默认的分组

现在我们在swagger-ui页面上观看一下，具体是对应的哪一部分的信息

很明显是页面右上角的位置

2.4.1.2 源码解析Swagger 配置信息 Docket.ApiInfo

在Docket类中找到下面这个构造方法，并且可以查看一下ApiInfo.DEFAULT，这个就是默认的

下面我们就来看一下这个的源码

在ApiInfo中，我们成功找到这个字段

将这个类往下翻翻，还会发现一个静态代码块：

我们发现静态代码块中的信息和swagger页面的信息是一个样子的，说明这个就是默认的配置，在类编译的时候就会加载（DEFAULT就是在这个地方被赋值的）


    static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

上面的这些信息对下的就是swagger-ui页面的下图信息

2.4.1.3 源码解析ApiInfo中的Contact参数

我们在源码中发现

其中DEFAULT_CONTACT是作者信息，如下图所示，发现都是空的

2.4.2 如何替换掉默认ApiInfo？

下面我们将这个配置改一下，如下代码所示


@Configuration   //加入到容器里面
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {

//  配置了Swagger的Docket实例
    @Bean
    public Docket docket() {
//        Docket有很多的配置，我们可以先配置一个apiInfo()
//        apiInfo()里面需要传入一个ApiInfo的参数，那我们就在下面定义一个
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo());
    }

//   配置Swagger信息 = apiInfo
    private ApiInfo apiInfo(){
//      下面的这套配置就把原来的static代码块覆盖掉
//      作者信息，通过查看源码得知
        Contact contact = new Contact("张靖奇", "https://blog.kuangstudy.com/", "1149345976@qq.com");
        return new ApiInfo(
                "张靖奇的API文档",
                "练习！！！！！！！",
                "v1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

之前的效果图：

如今的效果图：

假如说出不来下面的效果图，仍然是上面的效果图，给浏览器清理缓存再刷新即可

备注：这个框框圈出来的东西，至于文档名和描述信息有用，其他的没有用

2.4.3 Swagger配置扫描接口 Docket.select

我们再select()之后继续加点，我们发现只能再加上apis，paths

2.4.3.1 扫描指定的包

指定扫描com.example.controller包


    @Bean
    public Docket docket() {
//        Docket有很多的配置，我们可以先配置一个apiInfo()
//        apiInfo()里面需要传入一个ApiInfo的参数，那我们就在下面定义一个
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
//              select()参数里面需要传入一个Docket，可以返回一个ApiSelectorBuilder
                .select()
//               RequestHandlerSelectors,配置要扫描接口的方式
//                    basePackage("com.example")  指定扫描这个包
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

2.4.3.2 扫描全部的包


.apis(RequestHandlerSelectors.any())

2.4.3.3 都不扫描


.apis(RequestHandlerSelectors.none())

2.4.3.4 扫描类上的注解


 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

2.4.3.5 扫描方法上的注解


 .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))

2.4.3.6 过滤路径

ant() 过滤路径的

表示在com.example.controller包下的路径为/kuang开头的所有请求


.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.ant("/kuang/**"))

any()全部都过滤

none()全部都不过滤

regex()根据正则表达式过滤

2.4.4 配置是否启动Swagger

查看Docket源码，发现有一个enabed

默认为true，表示启动Swagger

如果为false，则Swagger不能在浏览器中访问

我们也可以把这个值改成false

注意！！这个点的时候，一定不要在build()后面点（从select到build是一套的）

此时重启之后访问不到页面

2.4.4.1 希望Swagger在生产环境中使用但发布时不适用

判断是不是生产环境 flag=false

注入enable(flag)

多配置是怎么来的？怎么确定是生产环境还是发布环境？

acceptsProfiles(Profiles profiles) 监听,返回boolean，其中Profiles是org.springframework.core.env

getDefaultProfiles() 获得默认的文件名，返回String[]

getActiveProfiles() 获得激活的文件名，返回String[]

如下代码所示，我们配置的是当在dev，test这两个版本下才能进入到swagger，重启刷新swagger-ui界面，他是直接访问不到的


    @Bean
    public Docket docket(Environment environment) {
//      获取项目的环境
//          这个地方是可变长参数，可以写好几个
        Profiles profiles = Profiles.of("dev","test");
//      如果是dev、test,这个地方的返回值就是true
        boolean flag = environment.acceptsProfiles(profiles);


//        Docket有很多的配置，我们可以先配置一个apiInfo()
//        apiInfo()里面需要传入一个ApiInfo的参数，那我们就在下面定义一个
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(flag)
                .apiInfo(apiInfo())
//              select()参数里面需要传入一个Docket，可以返回一个ApiSelectorBuilder
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

此时我们修改一下application.yaml文件，以及新增两个配置文件

application.yaml

#激活环境
spring:
  profiles:
    active: dev

application-dev.yaml

server:
  port: 8081

application-pro.yaml

server:
  port: 8082

修改及添加之后，再次访问页面，这次如果我们用8080端口是访问不到的，因为我们在application中配置的是dev环境，此时会直接向application-dev文件寻找，成为8081端口

2.4.5 配置Api文档的分组

2.4.5.1 配置多个组

配置多个Docket然后点就行

2.5 实体类配置

只要我们的接口中的返回值存在实体类，就会被扫描到Swagger(前提是Swagger会扫描到所在的包，一定看好范围)


@RestController
@RequestMapping("/test")
@Api(value = "测试一下")
public class TestController {


    @GetMapping("/userinfo")
    @ApiOperation("获取用户列表信息")
    public User getUserInfo(){

        User user = new User();

        return user;
    }
}


public class User {
    public String user;
    public String password;
}

效果如下图所示：

但是上边的都是英文，一般人会看不懂，但是我们可以加一些中文备注，这些中文备注就需要用到下面的注解

2.5.1 @ApiModel 与@ApiProperty

(31条消息) @ApiModel注解与@ApiModelProperty注解_我爱布朗熊的博客-CSDN博客

2.5.2 @ApiOperation

这个注解的作用就是给接口加了一个中文注释而已


    @GetMapping("/userinfo")
    @ApiOperation("获取用户列表信息")
    public User getUserInfo(){

        User user = new User("aaa","aaaaa");

        return user;
    }

2.5.3 @ApiParam


    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello";
    }

我爱布朗熊

关注

3
点赞
踩
26

收藏

觉得还不错? 一键收藏
打赏
0
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录