（三） spring boot 之使用Swagger配置详解

蔚落 2021-08-19 16:08 435阅读 0赞

为什么我会要专门在  springboot  系列中专门写一篇来介绍 swagger 呢，主要是因为我在日常的工作中真的是受够了这些不规范的接口，每次看自己负责的项目中的接口，心里都会默念一万句MMP。

所以我要写一篇博客来介绍 swagger 的配置详细解释，博文中有写的不对的地方希望大家指出，如果有什么好的想法也可以告诉我再加上。

还是要说一下，这些注解没有可以吗？  
完全可以，但是为了你自己看的更加清楚，也为了别人看的更加清楚，当然更为了你自己的人身安全，还是建议写上。

# springboot 配置 swagger 页面 #

[（一） SpringBoot 项目初始化 + 配置swagger页面][SpringBoot _ _ _swagger]

# swagger 页面的标题配置 #

页面的可配置项有很多，包括标题、版本、姓名、个人网站、email等等

值得注意的是一定要记得添加的三个注解  
@Configuration 将swagger页面配置到项目的加载中  
@EnableSwagger2 开启swagger页面的使用  
@Bean 将swagger页面的信息加载到Bean工厂中

package com.banana.demo.config;
    
    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.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;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
        @Bean
        public Docket api() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();
        }
    
        // 配置swagger页面的头部
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("Banana's SpringBoot APIs")            // 配置页面的标题
                    .description("这里是Banana的swagger页面")      // 配置页面的简介
                    .contact(new Contact("Banana",          // 配置页面联系，包括姓名，url，email
                            "https://blog.csdn.net/qq1515312832",
                            "dlt1997@outlook.com"))
                    .version("1.0")                               // 配置页面的版本
                    .build();
        }
    }

这里配置好之后我们的页面上就会显示出来我们所需要的信息，如下  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70]

# 对 Controller 添加注解 #

### 对 Controller 类添加注解 ###

首先，我们可以对整个 Controller 添加注解，对当前的 Controller 做一个注释  
![在这里插入图片描述][20191124141002378.png]  
对应的页面则是这样的，对应的Controller会显示为我们所需要的文字  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 1]

### 对 Controller 类中的接口添加注解 ###

#### 没有参数的接口 ####

![在这里插入图片描述][20191124141338179.png]  
使用@ApiOperation注解来对当前的接口做一个注释，value为当前接口的简述，notes为更为详细的叙述  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 2]

#### 有参数，但是没有在 uri 里的接口 ####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 3]  
这类的接口是有参数的，它的参数会自动拼接到url中传入进来，后端可以接收到，我们访问的url就会如下这样，userName就会拼接到url的后方

> http://localhost:8088/user/getUserListByName?userName=1

我们在swagger页面配置以后，参数就会显示出来  
name是参数的名称  
value是参数的含义  
dataType是参数的类型  
required是参数是否必须  
配置好就会显示如下界面：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 4]

#### uri中含有参数的接口 ####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 5]  
这个时候就会使用@PathVariable注解来标识参数，这个注解的适用场景是这个参数一定要在上面的uri中含有才可以，这样才能识别到参数，否则这个接口在运行时就会直接报错

#### 参数是实体的接口 ####

有特殊的情况，我们的参数中有实体，也可以当作json，所我们需要保证在swagger页面中比较好用，我们的实体都是一样的，但是我们把这些实体的模板自动化的加载出来就可以不用再去手动输入了。

所以我们就需要加@ApiParam的注解，来保证可以自动化的添加出来需要传入的实体。

@RequestBody注解的含义是要从请求体中获取到当前的参数来进行赋值。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 6]  
在swagger页面我们可以获得的配置就会变成这样，我们的参数中就会获得到我们需要的实体的参数，不需要再去重新写了，同时我们也可以保留我们所需要的，删去多余的，方便高效  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 7]

### 对实体添加swagger注解 ###

对于实体，我们可以添加@ApiModeal注解，来标识此实体是用于何处

对于实体中的参数，我们也可以标识出属性含义，使用@ApiModelProperty

package com.banana.demo.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel(value = "User:用户表")
    public class User { 
        @ApiModelProperty("用户 id")
        private String id;
        @ApiModelProperty("用户 姓名")
        private String user_name;
        @ApiModelProperty("用户 密码")
        private String user_password;
    
        public User() { 
        }
    
        public User(String id, String user_name, String user_password) { 
            this.id = id;
            this.user_name = user_name;
            this.user_password = user_password;
        }
    }

在swagger页面中的体现则如下  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 8]

# 推荐阅读 #

[@RequestParam，@PathParam，@PathVariable 等注解区别][RequestParam_PathParam_PathVariable]

[@ResponseBody使用须知][ResponseBody]

# 本系列文章 #

--------------------

**[Banana的SpringBoot系列博客][Banana_SpringBoot]**

[（一） SpringBoot 项目初始化 + 配置swagger页面][SpringBoot _ _ _swagger]

[（二） SpringBoot 整合 MyBatis-plus][SpringBoot _ MyBatis-plus]

[（三） SpringBoot之使用Swagger配置详解][SpringBoot_Swagger]

[（四） spring boot 多环境配置][spring boot]

[（五） spring boot 配置使用 redis][spring boot _ redis]

# 番外篇 #

[idea配置swagger页面自动启动][idea_swagger]

[SpringBoot _ _ _swagger]: https://blog.csdn.net/qq1515312832/article/details/103192645
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70]: /images/20210529/061476b3feb5422c9af3c8bf645a9c63.png
[20191124141002378.png]: /images/20210529/e61ad026afbc491b91323a172c952c49.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 1]: /images/20210529/7e6681ba992949cc96edcf60a7828d26.png
[20191124141338179.png]: /images/20210529/c738e9f0c0304f70be9a8c34d6895978.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 2]: /images/20210529/04b24321fcf54c17bd9efa606606c389.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 3]: /images/20210529/af6111bfda1c46a183df0944fb28f5d5.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 4]: /images/20210529/ce193b2ac32e413bb28d576d7c688d11.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 5]: /images/20210529/c8764d1ead894ebc9d094fced789d12c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 6]: /images/20210529/c1826d9f982c4f09870aa33bffae18fd.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 7]: /images/20210529/5e20a78314e449f48dc71683c034e6da.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxMTUxNTMxMjgzMg_size_16_color_FFFFFF_t_70 8]: /images/20210529/454c182b3e904cb9ba628ce33ac41801.png
[RequestParam_PathParam_PathVariable]: https://blog.csdn.net/u011410529/article/details/66974974
[ResponseBody]: https://blog.csdn.net/siwuxie095/article/details/79409772
[Banana_SpringBoot]: https://blog.csdn.net/qq1515312832/category_9540232.html
[SpringBoot _ MyBatis-plus]: https://blog.csdn.net/qq1515312832/article/details/103219467
[SpringBoot_Swagger]: https://blog.csdn.net/qq1515312832/article/details/103212461
[spring boot]: https://blog.csdn.net/qq1515312832/article/details/103232875
[spring boot _ redis]: https://blog.csdn.net/qq1515312832/article/details/103251335
[idea_swagger]: https://blog.csdn.net/qq1515312832/article/details/103198181