Swagger 增强（knife4j）自动生成Api 文档（SpringBoot & SpringCloud Gateway自动配置）

我会带着你远行 2023-07-22 11:30 2阅读 0赞

### 前言 ###

> 在经历了N次繁琐重复的swagger 配置之后（每一个项目都需要配置 SwaggerConfig），萌生了引入一个依赖自动帮我实现配置的观念，于是乎，`bubble-fireworks-starter-swagger` 诞生了…

### 项目介绍 ###

`bubble-fireworks` ，该项目是个人在日常工作中被N多重复性的工作所累，进而萌生了将重复性的东西归档，提高工作效率， 目前已发布RELEASE 版到中央仓库， 0.0.3-RELEASE 版本， 项目地址如下：

https://github.com/fxbin/bubble-fireworks

### 使用方法（springboot || springcloud gateway） ###

#### 1、引入pom依赖 ####

<dependency>
                <groupId>cn.fxbin.bubble</groupId>
                <artifactId>bubble-fireworks-starter-swagger</artifactId>
                <version>0.0.3-RELEASE</version>
            </dependency>

#### 一些注解的使用 ####

@Api：用在类上，说明该类的作用
    
    @ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了，看上去很有条理
    
    @ApiImplicitParams：用在方法上包含一组参数说明
    
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    
    　　paramType：参数放在哪个地方
    
    　　header 请求参数的获取：@RequestHeader
    
    　　query 请求参数的获取：@RequestParam
    
    　　path（用于restful接口） 请求参数的获取：@PathVariable
    
    　　body（不常用）
    
    　　form（不常用）
    
    　　name：参数名
    
    　　dataType：参数类型
    
    　　required：参数是否必须传
    
    　　value：参数的意思
    
    　　defaultValue：参数的默认值
    
    @ApiResponses：用于表示一组响应
    
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    
    　　code：数字，例如400
    
    　　message：信息，例如”请求参数没填好”
    
    　　response：抛出异常的类
    
    @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
    @ApiModel：使用在实体类上，描述实体类。
    @ApiModelProperty ：使用在实体类上的成员变量上，描述成员变量的含义。

#### 2、配置文件,开启权限认证（默认关闭） ####

bubble:
      fireworks:
        swagger:
          authorization:
            enabled: true

更多配置，请参考如下：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Z4YmluMTIz_size_16_color_FFFFFF_t_70]

#### 3、启动项目 ####

项目结构如下

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Z4YmluMTIz_size_16_color_FFFFFF_t_70 1]

#### 4、访问swagger增强文档 ####

访问规则： ip:port/doc.html

笔者这里如下：

http://localhost:9191/doc.html

效果图~~~  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Z4YmluMTIz_size_16_color_FFFFFF_t_70_pic_center]

参考文档：

[knife4j快速开始][knife4j]  
[springfox 源码系列][springfox]

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

– `end` –

`如有问题，请留言或者发送邮件，感谢您的阅读`

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Z4YmluMTIz_size_16_color_FFFFFF_t_70]: /images/20230528/eb35890267c04244ab4ac16833df5aae.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Z4YmluMTIz_size_16_color_FFFFFF_t_70 1]: /images/20230528/8f90f16a3d3c46cba525b1b7efff4cd3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Z4YmluMTIz_size_16_color_FFFFFF_t_70_pic_center]: /images/20230528/285229877ce44d8389da0fefc06353da.png
[knife4j]: https://doc.xiaominfo.com/
[springfox]: https://www.xiaominfo.com/2019/05/20/springfox-0/