Swagger3 使用介绍

喜欢ヅ旅行 2024-03-26 17:36 76阅读 0赞

> 这篇文章将介绍如何在 java 中使用 `swagger3`,

#### 文章目录 ####

*  一、Swagger3 简介
 *  二、与Swagger2注解对比
 *  三、 使用步骤
 *   *  1.导入依赖
     *  2.添加配置类
     *  3.常用注解
     *   *  1.@Tag注解
         *  2.@Operation注解
         *  3.@Schema注解
 *  四、页面访问
 *  五、常用配置
 *  六、总结

## 一、Swagger3 简介 ##

[官网地址][Link 1]:https://swagger.io/  
![在这里插入图片描述][2b71c3b913af4e36953daf1b3aaeba7c.png]

`Swagger` 是一个规范和完整的框架，用于生成可视化 RESTful 风格的 Web 服务。是一个简单且功能强大的API工具。几乎所有的现代编程语言，都在支持和使用。

Swagger2已经停止维护了，取而代之的是 swagger3，

## 二、与Swagger2注解对比 ##

之前在SpringBoot项目中一直使用的是`SpringFox`提供的Swagger库,已经很久没有更新了。  
`SpringDoc`是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3,  
是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大  
经常使用的Swagger注解，看看`SpringFox的和SpringDoc`的有啥区别，毕竟对比已学过的技术能更快掌握新技术;  
![在这里插入图片描述][ed7553094ad34337b210b125d6b8c8ab.png]

## 三、 使用步骤 ##

### 1.导入依赖 ###

<dependency>
           <groupId>org.springdoc</groupId>
           <artifactId>springdoc-openapi-ui</artifactId>
           <version>1.5.10</version>
       </dependency>

### 2.添加配置类 ###

进行SpringDoc的配置，使用`OpenAPI`来配置基础的文档信息，通过`GroupedOpenApi`配置分组的API文档，SpringDoc支持直接使用接口路径进行配置。

@Configuration
    public class SwaggerConfiguration {
        
    
        @Bean
        public OpenAPI customOpenAPI() {
        
            return new OpenAPI().info(new Info()
                    .title("代码平台 API")
                    .description("SpringDoc API 演示")
                    .version("v1.0.0")
            );
        }
    
        @Bean
        public GroupedOpenApi adminApi() {
        
            return GroupedOpenApi.builder()
                    .group("普通接口文档")
                    .pathsToMatch("/web/test/**").build();
        }
    
        @Bean
        public GroupedOpenApi homeApi() {
        
            return GroupedOpenApi.builder()
                    .group("首页相关接口")
                    .pathsToMatch("/query/excel/**")
                    .build();
        }

### 3.常用注解 ###

#### 1.@Tag注解 ####

用来描述一组操作的信息（通常用在controller控制层类上）  
![在这里插入图片描述][345a4535d9374061b73ee45f033f2789.png]例：

@Tag(name = "控制器")
    @RestController
    @RequestMapping("web/test")
    public class TestController {
        
    }

#### 2.@Operation注解 ####

用来描述接口信息（通常用在控制层的具体方法上）  
![在这里插入图片描述][90e8f01e402242aa979eeb9e5eb47f27.png]例：

@Tag(name = "控制器")
    @RestController
    @RequestMapping("web/test")
    public class TestController {
        
    
        @Operation(summary = "测试")
        @RostMapping("test")
        public ActionResult getUserInfo(String name) {
        
            return ActionResult.success(name+"成功");
        }
    }

#### 3.@Schema注解 ####

该注解用来定义模型及模型的属性（可以用在dto/vo以及其属性上）  
![在这里插入图片描述][1518f23e5d9f48278fc440397ebc5af2.png]

例：

@Data
    @Schema(name= "测试")
    public class ZnjExpertConsultFastLanguageInsertDTO {
        
    
        @Schema(description="主键id")
        private Integer id;
    }

## 四、页面访问 ##

> `http://ip:port/swagger-ui.html`

![在这里插入图片描述][c4cea81863d84006a6e6b46b1477f77c.png]

## 五、常用配置 ##

`SpringDoc还有一些常用的配置可以了解下。`

springdoc:
      swagger-ui:
        # 修改Swagger UI路径
        path: /swagger-ui.html
        # 开启Swagger UI界面
        enabled: true
      api-docs:
        # 修改api-docs路径
        path: /v3/api-docs
        # 开启api-docs
        enabled: true
      # 配置需要生成接口文档的扫描包
      packages-to-scan: com.test.controller
      # 配置需要生成接口文档的接口路径
      paths-to-match: /web/test/**,/query/excel/**

## 六、总结 ##

> 迁移到SpringDoc确实是一个更好的选择。确实很好用，和之前熟悉的用法差不多，`学习成本低`。

[Link 1]: https://swagger.io/
[2b71c3b913af4e36953daf1b3aaeba7c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/0dc9f3ee237b48bd92c70b537f454d4c.png
[ed7553094ad34337b210b125d6b8c8ab.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/1fb8f22b688d40e993c4fee92de250a7.png
[345a4535d9374061b73ee45f033f2789.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/813b89ef2b304dbb9c8e5ba0a61a86c3.png
[90e8f01e402242aa979eeb9e5eb47f27.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/7ebe73209cba4837945a8dac529cddf9.png
[1518f23e5d9f48278fc440397ebc5af2.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/c6fb8e28d048445cad31746337787410.png
[c4cea81863d84006a6e6b46b1477f77c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/ab72869f8392452993f8b682ade65b23.png