📢📢📢📣📣📣

哈喽！大家好，我是【一心同学】，一位上进心十足的【Java领域博主】！😜😜😜

✨【一心同学】的写作风格：喜欢用【通俗易懂】的文笔去讲解每一个知识点，而不喜欢用【高大上】的官方陈述。

✨【一心同学】博客的领域是【面向后端技术】的学习，未来会持续更新更多的【后端技术】以及【学习心得】。

✨如果有对【后端技术】感兴趣的【小可爱】，欢迎关注【一心同学】💞💞💞

❤️❤️❤️感谢各位大可爱小可爱！❤️❤️❤️ 

目录

一、背景

二、Swagger介绍

2.1一句话介绍 Swagger

2.2 Swagger特点

三、SpringBoot集成Swagger

四、配置Swagger API信息

五、配置Swagger自定义扫描接口

5.1 默认状态

5.2 配置扫描接口

5.3 配置接口扫描过滤

六、配置Swagger开关

6.1 enable

6.2 动态配置开关

七、 配置API分组

7.1 设置默认组名

7.2  配置多个组

八、实体配置

8.1 搭建实体

8.2 常用注解

8.2.1实体类注解

8.2.2 接口注解

8.3 常用注解

九、测试Swagger的使用

9.1 测试传参

这样的话就只有Post了。

9.2 传实体类参数

9.3 错误测试

十、拓展：其他皮肤

10.1 默认

 10.2 bootstrap-ui  

10.3 Layui-ui  

10.4 mg-ui  

结语

一、背景

无论是前端还是后端开发，都或多或少地被接口文档折磨过。

（1）前端经常抱怨后端给的接口文档与实际情况不一致。

（2）后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

二、Swagger介绍

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。

我们只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

2.1一句话介绍 Swagger

Swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。

2.2 Swagger特点

  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行，在线测试API
  • 支持多种语言 （如：Java，PHP等）
  • 官网：https://swagger.io/

三、SpringBoot集成Swagger

注意：使用JDK1.8+

搭建步骤：

1.新建一个SpringBoot-web项目

2.添加Maven依赖

springfox-swagger2

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

springfox-swagger-ui

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

3.编写Controller测试是否能正常运行

package com.yixin.demo.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {
    @RequestMapping("/test")
    public String test(){
        return "hello";
    }
}

浏览器：

正常运行！

4.使用Swagger，需要编写一个配置类-SwaggerConfig来配置 Swagger

package com.yixin.demo.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


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

5.测试进入Sawgger页面

重启主程序，访问 localhost:8080/swagger-ui.html

发现启动报错：

原因：是因为我们的SpringBoot版本过高

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


将其版本降低即可，改为2.5.4

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

我们重启主程序，访问 localhost:8080/swagger-ui.html
出现以下页面说明访问成功了。


 

这个界面是Swagger为我们提供的ui界面，我们可以在源码中找到它 

四、配置Swagger API信息

（1)Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

package com.yixin.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


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

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

(2）通过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<>()// 扩展
        );
    }

（3）Docket 实例关联上 apiInfo()

 @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//配置Swagger信息;
    }

重启主程序测试，可以看到Swagger信息已经变更成我们定义的信息

五、配置Swagger自定义扫描接口

5.1 默认状态

我们在这个ui界面中，可以看到扫描了两个controller接口；

一个是默认的/error请求，也就是我们启动springboot主程序未加配置默认访问8080端口的默认controller

另一个是我们自己写的/test请求，对应着MyController，由于我们用的@RequsetMapping注解，所以请求的方式有以上的六种

package com.yixin.demo.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

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

5.2 配置扫描接口

（1）构建Docket时通过select()方法配置扫描接口。

@Bean
public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())//配置Swagger信息
        .select()
        /**
         * apis():指定扫描的接口
         * RequestHandlerSelectors:配置要扫描接口的方式
         * basePackage:指定要扫描的包
         * any:扫面全部
         * none:不扫描
         * withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
         * withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
         */
        .apis(RequestHandlerSelectors.basePackage("com.yixin.demo.controller")
        .build();
        }

(2) 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到自定义路径下的controller

5.3 配置接口扫描过滤

作用：再次过滤指定路径下的请求接口

例如：
配置如何通过path过滤,即这里只扫描请求以/yixin开头的接口

paths(PathSelectors.ant("/yixin/**"))

实现测试：

（1）编写Controller

package com.yixin.demo.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

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

    @RequestMapping("/yixin/test")
    public String test2(){
        return "yixin";
    }
}

注意：我们现在的请求有两个“/test"和"/yixin/test"。

(2）编写配置

@Bean
public Docket docket() {

        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())//配置Swagger信息
        .select()
        /**
         * apis():指定扫描的接口
         * RequestHandlerSelectors:配置要扫描接口的方式
         * basePackage:指定要扫描的包
         * any:扫面全部
         * none:不扫描
         * withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
         * withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
         */
        .apis(RequestHandlerSelectors.basePackage("com.yixin.demo.controller"))
        /**
         * paths():过滤路径
         * PathSelectors:配置过滤的路径
         * any:过滤全部路径
         * none:不过滤路径
         * ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
         * regex:过滤指定路径:按照String的matches方法进行匹配
         */
        .paths(PathSelectors.ant("/yixin/**"))
        .build();
        }

分析：扫描路径com.yixin.demo.controller下的请求以/yixin开头的接口。

(3) 重启项目，访问 localhost:8080/swagger-ui.html

可以发现成功扫描到以/yixin请求开头的接口。

注意：.select().apis.paths.build是一套组合进行使用

六、配置Swagger开关

6.1 enable

通过Docket对象的.enable方法来配置swagger是否启动

  • true(默认）:开启
  • false:关闭
@Bean
public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())//配置Swagger信息
        .enable(false)//关闭swagger
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.yixin.demo.controller"))
        .paths(PathSelectors.ant("/yixin/**"))
        .build();
        }

更改为false后启动测试一下，发现无法进入到swagger页面


6.2 动态配置开关

需求：希望Swagger在开发环境中开启，在正式环境时不能使用

（1）判断是不是开发环境，可以设置一个flag表示用来表示：flag=1即表示生产环境
（2）将flag的值传给enable(flag)

实现：


(1) 在resources目录下新建两种springboot配置文件

开发环境：application-dev.properties

server.port=8090

正式环境：application-pro.properties

server.port=8070

目录如下：

(2)在主配置文件application.properties中激活开发环境

spring.profiles.active=dev

(3)到SwaggerConfig中的docket()方法中添加代码

a.首先给该方法传一个参数Environment的实例

Environment environment

b.设置要配置的Swagger环境：这里可以添加多个环境

Profiles profiles = Profiles.of("dev", "test");

c.通过environment.acceptsProfiles方法判断是否处在上一步设定的dev/test环境中，返回一个boolean的值，我们用flag接收

boolean flag = environment.acceptsProfiles(profiles);

d.修改enable中的参数为flag，即通过flag来判断是否开启Swagger

.enable(flag)//通过flag判断是否开启

完整代码：

package com.yixin.demo.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 //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment) {
        Profiles profiles = Profiles.of("dev", "test");
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yixin.demo.controller"))
                .paths(PathSelectors.ant("/yixin/**"))
                .build();
    }

    //配置文档信息
    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<>()// 扩展
        );
    }
}

(4) 启动主程序测试：由于激活了dev开发环境，所以可以访问localhost:8090/swagger-ui.html


注意：由于我们激活的是dev环境，所有端口号是8090

成功开启swagger，如果我们修改主配置文件，激活pro正式发布环境

application.properties

spring.profiles.active=pro

再次重启主程序测试，访问端口8070对应的地址localhost:8070/swagger-ui.html


注意pro的端口号是：8070

无法进入，因为pro环境不在我们配置的test/dev环境中，所以无法开启

七、 配置API分组


7.1 设置默认组名


如果没有配置分组，默认是default。

我们可以在docket通过.groupName中设置组名

@Bean
public Docket docket(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("yixin")// 配置分组
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.yixin.demo.controller"))
        .paths(PathSelectors.ant("/yixin/**"))
        .build();
        }

启测试，可以看到组名更改为yixin

7.2  配置多个组

上述我们成功修改了组名，但是只有一个组，如果我们想要多个组呢？

观察代码可以知道，一个Docket实例就对应着一个组，因此我们配置多个docket就对应着多个组

我们新增两个Docket的bean实例

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

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

再次重启测试，就可以看到多个组并选择

八、实体配置

8.1 搭建实体

（1）新建实体类

在主程序同级目录下新建pojo包，其中新建Blog实体类

package com.yixin.demo.pojo;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;


@AllArgsConstructor
@NoArgsConstructor
@Data
public class Blog {
    private String name;
    private Integer pwd;
}

注意：我们这里是导入了lombok依赖，自动添加get,set方法

<dependency>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
</dependency>

注：如果没有添加get,set方法，在swagger页面实体类中是看不到属性值的。

（2） 编写对应请求接口

编写完实体类，我们在model中还是看不到的，我们还需在MyController中新增一个方法返回实体类的实例对象即可映射到实体项中

@RequestMapping("/getBlog")
public Blog getBlog() {
        return new Blog();
        }

（3）启动测试

成功显示实体类Blog

注意：这里之所以会出现Blog，是因为接口方法（Controller)的返回值上的实体都会显示在这里

8.2 常用注解

8.2.1实体类注解

我们可以在实体类上和其属性上添加注解来解释对应的属性

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

（1）添加注解

package com.yixin.demo.pojo;


import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@AllArgsConstructor
@NoArgsConstructor
@Data
@ApiModel("博客实体")
public class Blog {

    @ApiModelProperty("博客")
    private String name;

    @ApiModelProperty("密码")
    private Integer pwd;
}

（2）重启测试，即可以看到注释信息

8.2.2 接口注解

我们同样可以在Controller类和其中的方法上添加相应的注解

  • @Api：为控制类添加注解
  • @ApiOperation：为控制方法添加注解

（1)添加注解

package com.yixin.demo.controller;

import com.yixin.demo.pojo.Blog;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "Hello控制类")
@RestController
public class MyController {
    @ApiOperation("Blog控制类")
    @RequestMapping("/getBlog")
    public Blog getBlog() {
        return new Blog();
    }
}

（2）重启即可看到对应的注解

8.3 常用注解

Swagger注解简单说明
@Api(tags = "xxx模块说明")作用在模块类上
@ApiOperation("xxx接口说明")作用在接口方法上
@ApiModel("xxxPOJO说明")作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")作用在参数、方法和字段上，类似@ApiModelProperty

九、测试Swagger的使用

9.1 测试传参

（1）我们在MyController中新增一个方法，参数为name，可以用@ApiParam给该参数添加注解

@GetMapping("/name")
public String getBlogName(@ApiParam("博客名") String name) {
        return name;
        }

 （2）重启测试，可以看到我们添加的注释
 


 

（3）我们可以简单测试一下，点击Try it out；然后以json的格式输入用户名，然后点击Execute执行
 


 

可以看到报错了，这是因为我们是使用的是Get方式：是通过URL的方式传递的，而不是通过请求体单独传参
 

结论：不能通过GET/HEAD方式进行请求传参。

我们将代码修改一下，将GetMapping改为RequestMapping（不能用GET/HEAD）或PostMapping即可

@RequestMapping("/name")
public String getBlogName(@ApiParam("博客名") String name) {
        return name;
        }

进入页面：

注意：只能使用以下五种方式进行传参，不能使用GET/HEAD传参。

重新测试：

再次以json的格式输入参数name，可以看到成功了

（4） 如果担心选到GET/HEAD，那么就将Controller定义为@PostMapping

@PostMapping("/name")
public String getBlogName(@ApiParam("博客名") String name) {
        return name;
        }



这样的话就只有Post了。




9.2 传实体类参数



（1）我们在MyController中新增一个方法，参数为Blog，可以用@ApiParam给该参数添加注解
 

@PostMapping("/blog")
public Blog getBlog(@ApiParam("博客") Blog blog) {
        return blog;
        }


（2）运行测试


 

（3）点击Execute测试


 

 

测试成功！

注意：一定要给Blog实体设置get和set方法，否则Response body相应体中博客名和密码都为会空。 



9.3 错误测试
 

@PostMapping("/blog")
public Blog getBlogs(@ApiParam("博客") Blog blog) {
        int i=10/0;
        return blog;
        }


此时测试肯定会报错，我们测试看看，可以看到500错误。


 

由此可见，swagger可以让我们很容易的进行前后端的交互测试


 

十、拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

10.1 默认

访问 http://localhost:8080/swagger-ui.htm

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



 

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


 


10.3 Layui-ui  

访问 http://localhost:8080/docs.html 


 




10.4 mg-ui  

访问 http://localhost:8080/document.html

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



结语



对于SpringBoot集成Swagger的知识点非常多，【一心同学】也是通过观看网上的资源【狂神】和一些Swagger相关的技术文章耗了不少时间才整理出来的，整理完成之后我发现Swagger的作用真的非常大，它提供的是一个接口文档而且还可以进行线上测试，这无疑是前后端开发人员的福音，所以对于这个Swagger工具，我们最好是去掌握它，因为它能够帮我们减少不少前后端交互的工作量。
 

# java # spring boot # intellij idea
Logo
GitCode 开源社区

旨在为数千万中国开发者提供一个无缝且高效的云端环境，以支持学习、使用和贡献开源项目。

更多推荐

【目标检测】目标检测的一些常用神经网络模型及方法

我的阶段性总结????文章目录1.概述1.2 目标检测的任务1.3 目标检测的分类2.R-CNN系列2.1 [R-CNN（Region with CNN features）](https://arxiv.org/pdf/1311.2524.pdf)2.2 [Fast R-CNN](https://www.cv-foundation.org/openaccess/content_iccv_2015/

avatar GitCode 开源社区
cover

用C++实现4种YOLO目标检测（内附完整代码）

avatar GitCode 开源社区
cover

静态时序分析：SDC约束命令create_generated_clock详解（上）

avatar GitCode 开源社区