springboot 集成 Swagger3（速通）

秒速五厘米 2023-10-10 21:56 52阅读 0赞

**→ [springboot 集成 Swagger2][springboot _ Swagger2] ←**

#### 目录 ####

*  1. 案例
 *  2. info 配置
 *  3. Docket 配置
 *   *  1. 开关配置
     *  2. 扫描路径
     *  3. 路径匹配
     *  4. 分组管理
 *  4. 常用注解
 *   *  1. 说明
     *  2. 案例

## 1. 案例 ##

这次直接使用 2.5.6 的 spring-boot 。

1.  依赖：
    
        <parent>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-parent</artifactId>
                <version>2.5.6</version>
                <relativePath/> 
            </parent>
        
            <dependencies>
                <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-web</artifactId>
                </dependency>
                
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-boot-starter</artifactId>
                    <version>3.0.0</version>
                </dependency>
                
                <dependency>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
                    <optional>true</optional>
                </dependency>
            </dependencies>
2.  启动类加注解 `@EnableOpenApi`
3.  新建测试类
    
        @RestController
        @RequestMapping("/test")
        public class SwaggerController {
              
            @GetMapping("/get")
            public String getStr(String str) {
              
                return "SELECT " + str;
            }
        
            @PostMapping("/post")
            public String postStr(String str) {
              
                return "CREATE " + str;
            }
        
            @PutMapping("/put")
            public String putStr(String str) {
              
                return "UPDATE " + str;
            }
        
            @NoSwagger
            @PatchMapping("/patch")
            public String patchStr(String str) {
              
                return "UPDATE " + str;
            }
        
            @DeleteMapping("/delete")
            public String deleteStr(String str) {
              
                return "DELETE " + str;
            }
        }
4.  访问 *http://127.0.0.1:8080/swagger-ui.html* ，没错，又是 Error 页面  
    ![00818b7a3f5d4db3ad961693a87d25cb.png][]

> 此部分参考：[https://blog.csdn.net/mmmm0584/article/details/117786055][https_blog.csdn.net_mmmm0584_article_details_117786055]
> 
> --------------------
> 
> 在swagger3.0中，swagger-ui.html的位置发生了变化：  
> ![0b28b72bfd834a139a3b55b68895270d.png][]  **→**  ![86fb1749e3c24af9ab63f486a8df42aa.png][]  
> 所以路径也变了：*http://127.0.0.1:8080/swagger-ui.html* → *http://127.0.0.1:8080/swagger-ui/index.html*

1.  访问 *http://127.0.0.1:8080/swagger-ui/index.html*  
    ![84387f17d0d24e59a0f95f731fdf1c77.png][]

## 2. info 配置 ##

新建一个配置类：

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.service.VendorExtension;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    import java.util.HashSet;
    
    @Configuration
    public class Swagger3Conf {
        
        @Bean
        public Docket createDocket() {
        
            return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                    .apiInfo(createApiInfo());
        }
    
        @Bean
        public ApiInfo createApiInfo() {
        
    //        // 写法一
    //        return new ApiInfoBuilder()
    //                .title("Swagger3 文档案例")
    //                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。")
    //                .version("1.0.1")
    //                .contact(
    //                        // name url email
    //                        new Contact("364.99°的文档", // 文档发布者名称
    //                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
    //                                "2190826197@qq.com" // 文档发布者的邮箱
    //                        )
    //                )
    //                .build();
            // 写法二
            return new ApiInfo(
                    "Swagger3 文档案例",
                    "Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                    "1.0.1",
                    "https://blog.csdn.net/m0_54355172",
                    new Contact("364.99°的文档", // 文档发布者名称
                                    "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                    "2190826197@qq.com" // 文档发布者的邮箱
                            ),
                    "364.99°",
                    "https://blog.csdn.net/m0_54355172",
                    new HashSet<>());
            }
    }

![56b8e138f8094a4fac69fc5ee1ed23a8.png][]

*  **`Docket`** Swagger 的实例，可通过 Docket 对象来配置 Swagger；
 *  **`ApiInfo`** 文件描述的配置对象。

## 3. Docket 配置 ##

### 1. 开关配置 ###

@Bean
        public Docket createDocket() {
        
            return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                    .enable(false)// 关闭文档
                    .apiInfo(createApiInfo());
        }

![26bcf8f701834b0ba71b696164f47cc0.png][]

**注意：** 一般只有在测试环境才会用到 Swagger，在生产环境中会把它关闭掉，为了安全与效率。

### 2. 扫描路径 ###

.select()
                    .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                    .build()

![0a2cc3ce962948549958674fd8178ea4.png][]

### 3. 路径匹配 ###

新建一个控制器：

@Api(tags = "other 接口 API")
    @RestController
    @RequestMapping("/other")
    public class OtherController {
        
        @GetMapping("getInfo")
        public String getInfo() {
        
            return "information";
        }
    }

.select()
                    .paths(PathSelectors.ant("/other/**"))
                    .build()

![567867bdf6314683b7b5dc2f2934f7dd.png][]

### 4. 分组管理 ###

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 java.util.HashSet;
    
    @Configuration
    public class Swagger3Conf {
        
        @Bean
        public Docket createDocket01() {
        
            return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                    .groupName("other 组")
                    .enable(true)// 关闭文档
                    .select()
                    .paths(PathSelectors.ant("/other/**"))
                    .build()
                    .apiInfo(createApiInfo());
        }
    
    	@Bean
        public Docket createDocket02() {
        
            return new Docket(DocumentationType.OAS_30)
                    .groupName("test 组")
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                    .build()
                    .apiInfo(
                            new ApiInfoBuilder()
                                    .title("Swagger3 文档案例")
                                    .build()
                    );
        }
    
        @Bean
        public ApiInfo createApiInfo() {
        
    //        // 写法一
    //        return new ApiInfoBuilder()
    //                .title("Swagger3 文档案例")
    //                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。")
    //                .version("1.0.1")
    //                .contact(
    //                        // name url email
    //                        new Contact("364.99°的文档", // 文档发布者名称
    //                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
    //                                "2190826197@qq.com" // 文档发布者的邮箱
    //                        )
    //                )
    //                .build();
            // 写法二
            return new ApiInfo(
                    "Swagger3 文档案例",
                    "Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                    "1.0.1",
                    "https://blog.csdn.net/m0_54355172",
                    new Contact("364.99°的文档", // 文档发布者名称
                                    "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                    "2190826197@qq.com" // 文档发布者的邮箱
                            ),
                    "364.99°",
                    "https://blog.csdn.net/m0_54355172",
                    new HashSet<>());
            }
    }

![073b18613abe4a28aad0e2cad3dedde6.png][]

## 4. 常用注解 ##

### 1. 说明 ###

和 [Swagger2][springboot _ Swagger2] 一样，其常用注解还是如下几个：

<table> 
 <thead> 
  <tr> 
   <th align="left">常用注解</th> 
   <th align="left">注解说明</th> 
   <th align="left">常用属性</th> 
   <th align="left">属性说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>@Api</code></td> 
   <td align="left">类注解，常用来给文档中的控制器取别名</td> 
   <td align="left">tags</td> 
   <td align="left">别名</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiOperation</code></td> 
   <td align="left">方法/类注解，常用来描述方法</td> 
   <td align="left">value<br>notes</td> 
   <td align="left">方法说明<br>方法备注</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiParam</code></td> 
   <td align="left">参数/方法/属性注解，常用来描述参数</td> 
   <td align="left">name<br>value<br>required</td> 
   <td align="left">参数名<br>补充描述<br>是否必须</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiIgnore</code></td> 
   <td align="left">方法/属性注解，使被标注方法不生成文档</td> 
   <td align="left">-</td> 
   <td align="left">-</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiImplicitParam</code></td> 
   <td align="left">方法注解，描述一个参数</td> 
   <td align="left">name<br>value<br>name<br>required<br>paramType<br>dataType<br>defaultValue</td> 
   <td align="left">参数名<br>补充说明<br><br>是否必传<br>参数位置（header、query、path）<br>参数类型（默认 String）<br>默认值</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiImplicitParams</code></td> 
   <td align="left">搭配 @ApiImplicitParam 一起使用，描述一组参数</td> 
   <td align="left"></td> 
   <td align="left"><img src="https://img-blog.csdnimg.cn/e0c9f21fcefb41c1becf6cf38eb85580.png" width="100%"></td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiResponse</code></td> 
   <td align="left">方法注解，表达一个错误的响应信息</td> 
   <td align="left">code<br>message<br>response</td> 
   <td align="left">整型<br>字符串<br>异常信息（默认 String 类型）</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiResponses</code></td> 
   <td align="left">搭配 @ApiResponse 一起使用，参考 @ApiImplicitParams</td> 
   <td align="left"></td> 
   <td align="left"></td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiModel</code></td> 
   <td align="left">类注解，当此实体类被作为返回类型用于 API 帮助文档中的接口方法中，此注解被解析</td> 
   <td align="left">value<br>description</td> 
   <td align="left">实体类名<br>补充描述</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiModelProperty</code></td> 
   <td align="left">属性注解，搭配 @ApiModel 使用</td> 
   <td align="left">value<br> example <br>hidden</td> 
   <td align="left">属性名<br> 示例<br>是否隐藏</td> 
  </tr> 
 </tbody> 
</table>

### 2. 案例 ###

import com.chenjy.swagger2.dto.TestDto;
    import io.swagger.annotations.*;
    import org.springframework.web.bind.annotation.*;
    import springfox.documentation.annotations.ApiIgnore;
    
    @Api(tags = {
        "test 接口 API"})
    @RestController
    public class SwaggerController {
        
    
        @ApiResponses({
        
                @ApiResponse(code = 1, message = "查询成功"),
                @ApiResponse(code = -1, message = "查询失败")
        })
        @ApiImplicitParams({
        
                @ApiImplicitParam(name = "name", value = "角色名", required = false, defaultValue = "张三"),
                @ApiImplicitParam(name = "num", value = "序列号", required = true)
        }
        )
        @PostMapping("/getInfo")
        public TestDto getInfo(String name, Integer num) {
        
            return new TestDto(name, num);
        }
        
        @ApiIgnore
        @GetMapping("/getStr")
        public String getStr(String name) {
        
            return name;
        }
    }

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel( value = "角色实体类", description = "存储数据并返回")
    public class TestDto {
        
        @ApiModelProperty( value = "姓名", example = "张三", hidden = false)
        private String name;
        @ApiModelProperty( value = "序列号", example = "1")
        private Integer num;
    }

![0ca0b470e0b54b41b7aac4f2b0b9efad.png][] ![ab7d4471ed0b4682a89f1a3552ca8f95.png][] ![0d78320a9ee24b34916c5a6ae82e13de.png][]

[springboot _ Swagger2]: https://blog.csdn.net/m0_54355172/article/details/130839916
[00818b7a3f5d4db3ad961693a87d25cb.png]: https://img-blog.csdnimg.cn/00818b7a3f5d4db3ad961693a87d25cb.png
[https_blog.csdn.net_mmmm0584_article_details_117786055]: https://blog.csdn.net/mmmm0584/article/details/117786055
[0b28b72bfd834a139a3b55b68895270d.png]: https://img-blog.csdnimg.cn/0b28b72bfd834a139a3b55b68895270d.png
[86fb1749e3c24af9ab63f486a8df42aa.png]: https://img-blog.csdnimg.cn/86fb1749e3c24af9ab63f486a8df42aa.png
[84387f17d0d24e59a0f95f731fdf1c77.png]: https://img-blog.csdnimg.cn/84387f17d0d24e59a0f95f731fdf1c77.png
[56b8e138f8094a4fac69fc5ee1ed23a8.png]: https://img-blog.csdnimg.cn/56b8e138f8094a4fac69fc5ee1ed23a8.png
[26bcf8f701834b0ba71b696164f47cc0.png]: https://img-blog.csdnimg.cn/26bcf8f701834b0ba71b696164f47cc0.png
[0a2cc3ce962948549958674fd8178ea4.png]: https://img-blog.csdnimg.cn/0a2cc3ce962948549958674fd8178ea4.png
[567867bdf6314683b7b5dc2f2934f7dd.png]: https://img-blog.csdnimg.cn/567867bdf6314683b7b5dc2f2934f7dd.png
[073b18613abe4a28aad0e2cad3dedde6.png]: https://img-blog.csdnimg.cn/073b18613abe4a28aad0e2cad3dedde6.png
[0ca0b470e0b54b41b7aac4f2b0b9efad.png]: https://img-blog.csdnimg.cn/0ca0b470e0b54b41b7aac4f2b0b9efad.png
[ab7d4471ed0b4682a89f1a3552ca8f95.png]: https://img-blog.csdnimg.cn/ab7d4471ed0b4682a89f1a3552ca8f95.png
[0d78320a9ee24b34916c5a6ae82e13de.png]: https://img-blog.csdnimg.cn/0d78320a9ee24b34916c5a6ae82e13de.png