SpringBoot与Swagger

柔光的暖阳◎ 2022-11-24 14:24 109阅读 0赞

Swagger，说白了其实就是专门为解决前后端开发人员的矛盾而生的，既可以有效解决前后端开发人员协商、沟通不及时的问题，也可以在很大程度上提高工作效率。Swagger号称世界上最流行的API框架。

对于后端开发人员来说，有了Swagger之后，不用再手写Wiki接口拼大量参数，避免手写错误；对代码侵入性低，采用全注解的方式，开发简单；方法参数名修改、新增、减少参数都可以直接生效，不用手动维护。

缺点：增加了开发成本，写接口还得再写一套参数配置

对前端开发来说，后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然；联调方便，如果出了问题，直接测试接口，实时检查参数和返回值，就可以快速定位是前端还是后端的问题。

对于测试人员来说，操作简单，不用了解具体代码就可以操作进行相关测试。

在我们的项目中集成Swagger时，首先必须导入相应的包和依赖。具体操作如下：

1.新建一个Spring Boot项目。命名为swagger。在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>

2.编写一个hello工程。在swagger包下新建一个controller的包，并新建一个HelloControl的java文件。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70][]

HelloController.java文件

package com.example.swagger.controller;
    
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    public class HelloController {
        @RequestMapping(value = "/hello")
        public String hello() {
            return "Hello World !";
        }
    }

测试运行：

![2020080616483991.png][]

3.配置swagger。编写SwaggerConfig文件。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 1][]

SwaggerConfig.java文件：

package com.example.swagger.config;
    
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    //开启Swagger
    @EnableSwagger2
    public class SwaggerConfig {
    
    }

虽然是个空的文件，但是本身就有默认的页面，此时我们访问swagger-ui.html网站，就会得到以下页面。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 2][]

以上界面是swagger本身的默认界面，我们可以看到此界面能够被分成四部分，即swagger信息、接口信息、实体类信息Models和组信息（选择框）。但是此时我们只是做了swagger的集成工作，还没有对其进行配置呢。那么，配置的时候，swagger有一个自己的Bean实例Docket，我们只需要配置这个Docket即可。我们对Docket进行配置之后就会发现我们在进入这个html界面时，和上面展示的完全不一样，因为我们使用Docket覆盖了其本身的配置。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 3][]

其实这些关于Swagger的配置信息，我们都可以从源码中得到，关于默认的界面是如何配置，以及如何修改配置等。

public class ApiInfo {
        public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
        public static final ApiInfo DEFAULT;
        private final String version;
        private final String title;
        private final String description;
        private final String termsOfServiceUrl;
        private final String license;
        private final String licenseUrl;
        private final Contact contact;
        private final List<VendorExtension> vendorExtensions;
    }

之前说过，swagger-ui.html可以被分为四部分，其中有一部分叫做接口信息，我们点进去会发现，有众多的接口。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 4][]

为什么会有这么多的请求方式呢？这是因为我们在使用RequestMapping的时候没有指定具体的请求方式，所以它才会展示出所有的请求方式。那么，我们如何才能让Swagger不扫描所有接口，而由我们自定义扫描呢？这就是我们接下来要处理的事情，配置swagger扫描接口。

swagger配置扫描接口的时候是通过Docket的select()方法来实现的。

public Docket docket() {
            Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                    //配置要扫描接口的方式，指定只扫描controller包下的方法
                    .select().apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                    .build();
            return docket;
        }

启动运行之后我们发现，之前的接口信息里现在只有hello-controller接口了。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 5][]

除此之外，我们还可以配置是否启动swagger。这个其实挺简单的，通过源码可知道，只需要修改一个参数而已。

public Docket(DocumentationType documentationType) {
            this.apiInfo = ApiInfo.DEFAULT;
            this.groupName = "default";
            this.enabled = true;
            this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
            this.applyDefaultResponseMessages = true;
            this.host = "";
            this.pathMapping = Optional.absent();
            this.apiSelector = ApiSelector.DEFAULT;
            this.enableUrlTemplating = false;
            this.vendorExtensions = Lists.newArrayList();
            this.documentationType = documentationType;
        }

public Docket docket() {
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo()).enable(false);
            return docket;
        }

我们发现，网页显示找不到，让我们看控制台，其实控制台也没有。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 6][]

如果说，我们只需要swagger在生产环境中使用，不让其在发布的时候使用。那我们又该如何处理呢？这就涉及到了多环境配置文件的情况。我们需要首先判断是不是生产环境，如果不是，那就直接设置enable参数为false就行。

首先，我们新创建两个不同环境下的配置文件，并做简单的端口的配置，在主配置文件中选择我们要使用的环境。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 7][]

之后我们在SwaggerConfig.java的 配置文件中判断我们的环境是否为开发环境，如果是，则配置swagger。

public Docket docket(Environment environment) {
    
            //设置要显示swagger的环境
            Profiles profiles = Profiles.of("dev");
            //通过environment.acceptsProfiles()来判断是否处在自己设定的环境中
            boolean flag = environment.acceptsProfiles(profiles);
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(flag);
            return docket;
        }

判断我们的环境是否为"dev"环境，并返回一个布尔值，让这个布尔值去作为enable的值，直接来控制swagger的启动与否。如上代码所示，我们选择在开发环境下启动swagger的配置，而且我们在配置文件中也确实选择了开发环境，那么启动运行之后效果如下。需要注意的是，我们修改了开发环境的端口号，所以不能再使用8080端口去访问了。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 8][]

接下来我们考虑配置一下swagger的组信息，即之前提到过的swagger的主页被分为四部分中的右上角的组信息，默认分组为default。

![20200807111717558.png][]

配置组信息就是修改一下groupName()。

//配置swagger组信息
        public Docket docket() {
    
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo()).groupName("张三");
            return docket;
        }

启动之后，我们看到，组信息已经明显被改掉了。

![20200807112229718.png][]

但是，这样的话我们只设置了一个分组。我们如果要设置多个分组的话要如何做呢？首先，我们需明白，这个分组的出现是因为docket实例的出现，那么我们就可以使用多个docket实例来设置多个分组。

@Bean
        public Docket docket1() {
    
            Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("ABC");
            return docket;
        }
        @Bean
        public Docket docket2() {
    
            Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("abc");
            return docket;
        }
    
        @Bean
        public Docket docket3() {
    
            Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("@#$");
            return docket;
        }

如上所示，我们新建了三个docket实例，需要注意的是，每个docket实例，都必须使用@Bean。加上之前的，现在我们有四个分组了，我们启动程序看一下。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 9][]

在创建docket实例时，组名的选择不要使用特殊符号，不然会出错。由于我们新增加的三个docket实例没有配置apiInfo()文档信息，所以还是默认的接口信息和swagger信息等。但是我们"张三"组使用了自己配置的swagger文档信息。

这样的话我们就完成了swagger的多个分组的配置，我们其实可以理解，当多个组在协同工作时，就可以选择自己所在的组了，而每个组对swagger的 配置可能不一样，就像我们示例给出的那样，有配置了的，有没配置的，那么这种多样性可能在协同工作的时候就体现出来了。

那么此时我们对接口信息、swagger基本信息和分组信息都做了一些操作，swagger界面的四个部分如今就只剩下实体类models了。既然models是个实体类，那么我们首先新建一个实体类User。

在新建实体类之前，我们发现，在ABC组中，它的实体类是空的。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 10][]

我们在pojo文件下创建User实体类，内容如下：

package com.example.swagger.pojo;
    
    public class User {
        public String name;
        public String pwd;
    }

并在HelloController.java文件中添加其获取方式：

@RestController
    public class HelloController {
        @GetMapping(value = "/hello")
        public String hello() {
            return "Hello World !";
        }
    
        //只要我们的接口中，返回值中存在实体类，就会被扫描到swagger中
        @PostMapping(value = "/user")
        public  User user() {
            return new User();
        }
    }

之后，启动运行。很明显，User类已经被ABC组扫描到了。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 11][]

当然，User实体类也可以被"abc"，"123"组扫描到。

除此之外，我们为了避免有些类难以理解和其字段较多的现象，我们还可以使用一些方法来为类或者字段添加注释。

// @ApiModel只能用来为class添加注释
    @ApiModel("用户实体类")
    public class User {
        // @ApiModelProperty用来为字段添加注释
        @ApiModelProperty("用户名")
        public String name;
        @ApiModelProperty("密码")
        public String pwd;
    }

之后，启动运行就会看到关于类和字段的注释。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 12][]

除此之外，我们还能发现，swagger具有测试的功能。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 13][]

因为这个hello()方法是直接输出的，所以我们不用传递参数，直接测试之后就会显示200提示码，表示成功。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 14][]

参考自狂神发表在哔哩哔哩上的《狂神说Java》的相关视频，在此表示感谢！

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70]: /images/20221124/86c4aefade184751be0c66596bb4de91.png
[2020080616483991.png]: /images/20221124/6ce55d5eb1b54fea959a4b44e2a4ab04.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 1]: /images/20221124/403fbe66a35a4f7898fe356fc7bcac35.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 2]: /images/20221124/f5fdd91bd1eb46aa81af1ba42ac7b443.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 3]: /images/20221124/0487306e7ce946969334b4e63d34e428.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 4]: /images/20221124/76a8e0ae75e94840b6fb72fee2288b68.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 5]: /images/20221124/28660bf36cb64558be0572918338db33.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 6]: /images/20221124/ae7ba6995d5e456ba1192adfe500c46d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 7]: /images/20221124/e938d022e0a34c50b0f45dc370cf4cc6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 8]: /images/20221124/eee0998692c445b3b7cda3ac91949677.png
[20200807111717558.png]: /images/20221124/3c6ede3fc545463099447f474eef078d.png
[20200807112229718.png]: /images/20221124/5312245046da427ebd21c789cb475bdb.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 9]: /images/20221124/9fd8b7316197481cb4986cd99ceac9b7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 10]: /images/20221124/b7b23de1778b46e589973d3c8203ccfd.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 11]: /images/20221124/72dfc1ea27414dd9b2217336db4e970e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 12]: /images/20221124/c63d900cf7b8478aae1ba685cc42d00f.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 13]: /images/20221124/7c7c7115132c4dcc9d68af3199a0534c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW9tdWJhaQ_size_16_color_FFFFFF_t_70 14]: /images/20221124/4d4ff4ed0ce9436e921575be42832030.png