SpringBoot整合Swagger，让开发更遍历

Love The Way You Lie 2024-05-24 12:59 0阅读 0赞

![在这里插入图片描述][8d8e0d8a542946af858489a536162608.gif_pic_center]

> 个人简介：Java领域新星创作者；阿里云技术博主、星级博主、专家博主；正在Java学习的路上摸爬滚打，记录学习的过程~  
> 个人主页：[.29.的博客][.29.]  
> 学习社区：[进去逛一逛~][Link 1]

> [![在这里插入图片描述][730dbbe6f8bf48a9b2cf2f21e467674e.png_pic_center]][730dbbe6f8bf48a9b2cf2f21e467674e.png_pic_center 1]

#### SpringBoot整合Swagger，让开发更遍历 ####

*  ?
 *   *  Swagger介绍
     *  SpringBoot整合swagger
     *  Swagger常用注解介绍

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

## ? ##

### Swagger介绍 ###

**Swagger** 是一种流行的开源工具集，用于设计、构建、记录和使用 RESTful Web 服务的 API( https://swagger.io/ )。它包含了一系列工具，可以帮助开发人员在开发 API 时更加高效地进行设计、测试和文档编写。**下面是 Swagger 的一些主要功能和组件：**

1.  **API 文档自动生成：** Swagger 可以根据代码中的注解自动生成 API 文档。开发人员只需要在代码中添加一些特定的注解，描述 API 的路径、参数、响应等信息，Swagger 就可以自动扫描代码并生成相应的 API 文档。
2.  **可视化 API 文档：** Swagger 生成的 API 文档以可视化的形式呈现，包括 API 的路径、HTTP 方法、参数、响应等信息，使开发人员可以清晰地了解 API 的使用方式和接口规范。
3.  **交互式 API 测试工具：** Swagger UI 是 Swagger 提供的一个交互式 API 测试工具，可以让开发人员直接在浏览器中测试 API，无需使用额外的工具或插件。通过 Swagger UI，开发人员可以输入参数、发送请求，并查看实际的响应结果，从而快速验证 API 的正确性和可用性。
4.  **API 文档的版本控制：** Swagger 支持多版本的 API 文档管理，开发人员可以为不同版本的 API 编写不同的文档，并通过 Swagger UI 来方便地切换和查看不同版本的 API。
5.  **集成开发环境支持：** Swagger 可以集成到各种常见的集成开发环境（IDE）中，如 Eclipse、IntelliJ IDEA 等，提供了便捷的 API 设计和文档编写功能。
6.  **与多种编程语言和框架的兼容性：** Swagger 不仅支持 Java，还支持多种其他编程语言和框架，如 Python、Node.js、Ruby 等，开发人员可以在不同的项目中使用 Swagger 来进行 API 的设计和文档编写。

**综合来说，Swagger 提供了一套完整的工具集，帮助开发人员更加高效地设计、构建和文档化 RESTful API，提升了团队协作效率，降低了开发成本，同时也提升了 API 的可读性和可维护性。**

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

### SpringBoot整合swagger ###

`1 引入Maven坐标`：

> Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>

`2 创建一个Swagger配置类`：

> SwaggerConfiguration.java

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;
    
    /**
     * @author .29.
     * @create 2024-05-13 10:43
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfiguration {
        
    
        @Bean
        public Docket buildDocket() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(buildApiInfo())
                    .select()
                    // 要扫描的API(Controller)基础包
                    .apis(RequestHandlerSelectors.basePackage("com.heima"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo buildApiInfo() {
        
            Contact contact = new Contact(".29.","","");
            return new ApiInfoBuilder()
                    .title(".29.仿今日头条-平台管理API文档")
                    .description(".29.仿今日头条后台api")
                    .contact(contact)
                    .version("1.0.0").build();
        }
    }

> 让我解释一下这段代码的主要内容：
> 
> 1.  `@Configuration`：这个注解表明这是一个配置类，它会在 Spring 应用程序启动时被加载。
> 2.  `@EnableSwagger2`：这个注解用于启用 Swagger2 的支持。
> 3.  `@Bean`：这个注解表明 `buildDocket()` 方法将会产生一个 Spring Bean，并将其加入到 Spring 容器中。
> 4.  `buildDocket()` 方法：这个方法创建并配置了一个 `Docket` 对象，用于配置 Swagger 的基本信息和扫描规则。具体来说：
>     
>      *  使用 `DocumentationType.SWAGGER_2` 指定了 Swagger 的文档类型为 Swagger 2.0。
>      *  使用 `apiInfo(buildApiInfo())` 方法设置 API 文档的基本信息，包括标题、描述、联系人信息和版本号。
>      *  使用 `select()` 方法开始配置 API 选择器，通过 `apis(RequestHandlerSelectors.basePackage("com.heima"))` 指定了要扫描的 API(Controller) 的基础包路径为 “com.heima”。
>      *  使用 `paths(PathSelectors.any())` 方法指定了所有路径都应该被包含在 API 文档中。
>      *  最后使用 `build()` 方法来构建 `Docket` 对象。
> 5.  `buildApiInfo()` 方法：这个方法创建并配置了 `ApiInfo` 对象，用于设置 API 文档的基本信息。具体来说：
>     
>      *  创建了一个 `Contact` 对象，用于设置联系人信息。
>      *  使用 `ApiInfoBuilder` 构建器设置了 API 文档的标题、描述、联系人信息和版本号。
>      *  最后使用 `build()` 方法构建 `ApiInfo` 对象。
> 
> 这段代码配置了 Swagger 生成 API 文档的基本信息，并指定了扫描哪些包中的 Controller 类来生成 API 文档。

`3 设置Swagger相关功能的自动配置`：

> resources目录下新增文件：resources/META-INF/Spring.factories
> 
> ![在这里插入图片描述][25a7e70f1eed447f87582fd399bcbb61.png_pic_center]

# Spring自动配置相关参数（参数通常是一个以逗号分隔的类名列表，每个类名表示一个自动配置类。）
    org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
      com.heima.common.swagger.SwaggerConfiguration

⭐`在Java类中添加Swagger的注解即可生成Swagger接口文档`⭐

⭐`访问Swagger文档：http://{你的IP}:{你的项目服务端口}/swagger-ui.html`⭐

http://localhost:51801/swagger-ui.html

> ![在这里插入图片描述][753ab0316adf4d35b31677161322abe7.png]

### Swagger常用注解介绍 ###

`@Api`：修饰整个类，描述Controller的作用

`@ApiOperation`：描述一个类的一个方法，或者说一个接口

`@ApiParam`：单个参数的描述信息

`@ApiModel`：用对象来接收参数

`@ApiModelProperty`：用对象接收参数时，描述对象的一个字段

`@ApiResponse`：HTTP响应其中1个描述

`@ApiResponses`：HTTP响应整体描述

`@ApiIgnore`：使用该注解忽略这个API

`@ApiError` ：发生错误返回的信息

`@ApiImplicitParam`：一个请求参数

`@ApiImplicitParams`：多个请求参数的描述信息

**@ApiImplicitParam属性：**

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>取值</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td></td> 
   <td>查询参数类型</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>path</td> 
   <td>以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>query</td> 
   <td>直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>body</td> 
   <td>以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>header</td> 
   <td>参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>form</td> 
   <td>以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td></td> 
   <td>参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>Long</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>String</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td></td> 
   <td>接收参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td></td> 
   <td>接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td></td> 
   <td>参数是否必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>true</td> 
   <td>必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>false</td> 
   <td>非必填</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td></td> 
   <td>默认值</td> 
  </tr> 
 </tbody> 
</table>

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

[![在这里插入图片描述][20a7f1b58dfb4660b75d7f021c157d57.png_pic_center]][20a7f1b58dfb4660b75d7f021c157d57.png_pic_center 1]

[8d8e0d8a542946af858489a536162608.gif_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/9c23ff97b481456eadf4ebe11bb6ef25.gif
[.29.]: https://blog.csdn.net/ebb29bbe?spm=1018.2226.3001.5343
[Link 1]: https://bbs.csdn.net/forums/185241f773fb401b8ca7994dc3d02333?joinKey=cyru4ex9o7wq-mz6v1koj5x-1-add3ae8dc3827dbbd4360c79af92bbbe
[730dbbe6f8bf48a9b2cf2f21e467674e.png_pic_center]: https://img-blog.csdnimg.cn/direct/730dbbe6f8bf48a9b2cf2f21e467674e.png#pic_center
[730dbbe6f8bf48a9b2cf2f21e467674e.png_pic_center 1]: https://blog.csdn.net/ebb29bbe/category_12275567.html?spm=1001.2014.3001.5482
[25a7e70f1eed447f87582fd399bcbb61.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/31da6a6a2e054d8eafe6a3049f20a9e7.png
[753ab0316adf4d35b31677161322abe7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/1df6985ea417417cb5e58c8401bbaaee.png
[20a7f1b58dfb4660b75d7f021c157d57.png_pic_center]: https://img-blog.csdnimg.cn/20a7f1b58dfb4660b75d7f021c157d57.png#pic_center
[20a7f1b58dfb4660b75d7f021c157d57.png_pic_center 1]: https://blog.csdn.net/ebb29bbe?type=blog

SpringBoot整合Swagger，让开发更遍历

发表评论取消回复

还没有评论，来说两句吧...

相关阅读