SpringBoot原理分析 | 开源框架：Swagger集成

阳光穿透心脏的1/2处 2024-04-22 19:05 13阅读 0赞

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

> [💗wei\_shuo的个人主页][wei_shuo]
> 
> 💫[wei\_shuo的学习社区][wei_shuo 1]
> 
> 🌐Hello World ！

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

### Swagger ###

> Swagger 是一个用于构建、文档化和测试 RESTful API 的开源框架。它可以通过自动生成 API 文档和客户端 SDK，从而简化了 API 的开发和维护工作。Swagger 支持多种编程语言和平台，包括 Java、Python、Node.js 等；Swagger 是一个非常实用的 API 开发和文档化工具，可以大大提高 API 的开发效率和质量
> 
>  *  API 文档自动生成：通过注解和配置文件，Swagger 可以自动生成 API 的文档，包括接口的请求和响应参数、请求方式、返回结果等
>  *  API 测试工具：Swagger 提供了一个基于 Web 的 API 测试工具，可以方便地测试 API 的各种请求和响应结果
>  *  客户端 SDK 生成：Swagger 可以根据 API 文档自动生成各种客户端 SDK，包括 Java、Python、Node.js 等
>  *  API 视图展示：Swagger 可以将 API 文档以清晰的视图展示出来，方便用户查看和理解 API 的使用方式

#### Springboot集成Swagger ####

>  *  依赖导入
> 
>     
>             <dependency>
>                 <groupId>io.springfox</groupId>
>                 <artifactId>springfox-boot-starter</artifactId>
>                 <version>3.0.0</version>
>             </dependency>
>             
>             <dependency>
>                 <groupId>io.springfox</groupId>
>                 <artifactId>springfox-swagger2</artifactId>
>                 <version>3.0.0</version>
>             </dependency>
>             
>             <dependency>
>                 <groupId>io.springfox</groupId>
>                 <artifactId>springfox-swagger-ui</artifactId>
>                 <version>3.0.0</version>
>             </dependency>
> 
>  *  controller/SwaggerController.java
> 
>     package com.wei.config;
>     
>     import org.springframework.context.annotation.Configuration;
>     import springfox.documentation.swagger2.annotations.EnableSwagger2;
>     
>     @Configuration
>     //开启Swagger2
>     @EnableSwagger2
>     public class SwaggerConfig {
>          
>     
>     }
> 
>  *  SpringbootSwaggerApplication.java
> 
>     package com.wei;
>     
>     import org.springframework.boot.SpringApplication;
>     import org.springframework.boot.autoconfigure.SpringBootApplication;
>     import org.springframework.web.servlet.config.annotation.EnableWebMvc;
>     import springfox.documentation.oas.annotations.EnableOpenApi;
>     
>     @SpringBootApplication
>     @EnableWebMvc
>     @EnableOpenApi
>     public class SpringbootSwaggerApplication {
>          
>     
>         public static void main(String[] args) {
>          
>             SpringApplication.run(SpringbootSwaggerApplication.class, args);
>         }
>     
>     }
> 
>  *  controller/HelloController.java
> 
>     package com.wei.controller;
>     
>     import org.springframework.web.bind.annotation.RequestMapping;
>     import org.springframework.web.bind.annotation.RestController;
>     
>     @RestController
>     public class HelloController {
>          
>     
>         @RequestMapping("/hello")
>         public String hello(){
>          
>             return "Hello,Swagger!";
>         }
>     }
> 
>  *  浏览器访问：http://localhost:8080/swagger-ui/index.html
> 
> ![在这里插入图片描述][95cfb857bba340c48d056321f0ed2473.png_pic_center]

#### 配置Swagger信息 ####

>  *  confing/SwaggerConfig.java
> 
>     package com.wei.config;
>     
>     import org.springframework.context.annotation.Bean;
>     import org.springframework.context.annotation.Configuration;
>     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;
>     
>     import java.util.ArrayList;
>     
>     @Configuration
>     //开启Swagger2
>     @EnableSwagger2
>     public class SwaggerConfig {
>          
>     
>         //配置Swagger的Bean实例
>         @Bean
>         public Docket docket(){
>          
>             return new Docket(DocumentationType.SWAGGER_2)
>                     .apiInfo(apiInfo());
>         }
>     
>         //配置Swagger信息apiInfo
>         private ApiInfo apiInfo(){
>          
>     
>             //作者信息
>             Contact contact = new Contact("wei_shuo", "#", "1096075493@qq.com");
>     
>             return new ApiInfo(
>                     "wei_shuo API文档",
>                     "开源……",
>                     "1.0",
>                     "urn:tos",
>                     contact,
>                     "Apache 2.0",
>                     "http://www.apache.org/licenses/LICENSE-2.0",
>                     new ArrayList()
>             );
>         }
>     
>     }
> 
>  *  浏览器运行
> 
> ![在这里插入图片描述][b5e1917201aa40d2b44d8b6563cbb0a0.png_pic_center]

#### 配置扫描接口 ####

>  *  confing/SwaggerConfig.java
> 
>     package com.wei.config;
>     
>     import com.wei.controller.HelloController;
>     import org.springframework.context.annotation.Bean;
>     import org.springframework.context.annotation.Configuration;
>     import org.springframework.stereotype.Controller;
>     import org.springframework.web.bind.annotation.GetMapping;
>     import org.springframework.web.bind.annotation.RestController;
>     import springfox.documentation.RequestHandler;
>     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;
>     
>     import java.util.ArrayList;
>     
>     @Configuration
>     //开启Swagger2
>     @EnableSwagger2
>     public class SwaggerConfig {
>          
>     
>         //配置Swagger的Bean实例
>         @Bean
>         public Docket docket(){
>          
>             return new Docket(DocumentationType.SWAGGER_2)
>                     .apiInfo(apiInfo())
>                     .select()
>                     //RequestHandlerSelectors 配置要扫描接口的方式
>                     //basePackage("com.wei.controller") 指定扫描包
>                     //.apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
>                     //any() 扫描全部
>                     //.apis(RequestHandlerSelectors.any())
>                     //none() 不扫描
>                     //.apis(RequestHandlerSelectors.none())
>                     //withClassAnnotation() 扫描类注解
>                     //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
>                     //withMethodAnnotation(GetMapping.class) 扫描方法注解
>                     //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
>                     .apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
>                     //过滤路径
>                     .paths(PathSelectors.ant("/hello/**"))
>                     .build();
>         }
>     
>         //配置Swagger信息apiInfo
>         private ApiInfo apiInfo(){
>          
>     
>             //作者信息
>             Contact contact = new Contact("wei_shuo", "#", "1096075493@qq.com");
>     
>             return new ApiInfo(
>                     "wei_shuo API文档",
>                     "开源……",
>                     "1.0",
>                     "urn:tos",
>                     contact,
>                     "Apache 2.0",
>                     "http://www.apache.org/licenses/LICENSE-2.0",
>                     new ArrayList()
>             );
>         }
>     
>     }
> 
>  *  配置是否启用swagger
> 
>     //配置Swagger的Bean实例
>         @Bean
>         public Docket docket(){
>          
>             return new Docket(DocumentationType.SWAGGER_2)
>                     .apiInfo(apiInfo())
>                     //是否启用swagger默认true
>                     .enable(false)
>                     .select()
>                     .apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
>                     .build();
>         }

#### 案例：根据项目环境，配置swagger ####

>  *  分别创建properties的开发，测试，发布
> 
> ![在这里插入图片描述][34ac1894217644fe8d3e70abef0f1229.png_pic_center]

>  *  application.properties
> 
>     spring.profiles.active=dev
>     #spring.profiles.active=test
>     #spring.profiles.active=prod
> 
>  *  application-dev.properties
> 
>     server.port=8081
> 
>  *  application-test.properties
> 
>     server.port=8082
> 
>  *  application-prod.properties
> 
>     server.port=8083
> 
>  *  confing/SwaggerConfig.java
> 
>     package com.wei.config;
>     
>     import com.wei.controller.HelloController;
>     import org.springframework.context.annotation.Bean;
>     import org.springframework.context.annotation.Configuration;
>     import org.springframework.core.env.Environment;
>     import org.springframework.core.env.Profiles;
>     import org.springframework.stereotype.Controller;
>     import org.springframework.web.bind.annotation.GetMapping;
>     import org.springframework.web.bind.annotation.RestController;
>     import springfox.documentation.RequestHandler;
>     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;
>     
>     import java.util.ArrayList;
>     
>     @Configuration
>     //开启Swagger2
>     @EnableSwagger2
>     public class SwaggerConfig {
>          
>     
>         //配置Swagger的Bean实例
>         @Bean
>         public Docket docket(Environment environment){
>          
>     
>             //设置要显示的swagger环境
>             Profiles profiles = Profiles.of("dev","test","prod");
>     
>             //通过environment.acceptsProfiles()判断项目环境
>             boolean flag = environment.acceptsProfiles(profiles);
>     
>             return new Docket(DocumentationType.SWAGGER_2)
>                     .apiInfo(apiInfo())
>                     //是否启用swagger默认true
>                     .enable(flag)
>                     .select()
>                     .apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
>                     .build();
>         }

#### 配置API分组 ####

>  *  API文档分组
> 
>     //API文档分组
>     .groupName("wei")
> 
>     package com.wei.config;
>     
>     import com.wei.controller.HelloController;
>     import org.springframework.context.annotation.Bean;
>     import org.springframework.context.annotation.Configuration;
>     import org.springframework.core.env.Environment;
>     import org.springframework.core.env.Profiles;
>     import org.springframework.stereotype.Controller;
>     import org.springframework.web.bind.annotation.GetMapping;
>     import org.springframework.web.bind.annotation.RestController;
>     import springfox.documentation.RequestHandler;
>     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;
>     
>     import java.util.ArrayList;
>     
>     @Configuration
>     //开启Swagger2
>     @EnableSwagger2
>     public class SwaggerConfig {
>          
>     
>         @Bean
>         public Docket docker1(){
>          
>             return new Docket(DocumentationType.SWAGGER_2).groupName("A");
>         }
>     
>         @Bean
>         public Docket docker2(){
>          
>             return new Docket(DocumentationType.SWAGGER_2).groupName("B");
>         }
>     
>         @Bean
>         public Docket docker3(){
>          
>             return new Docket(DocumentationType.SWAGGER_2).groupName("C");
>         }
>     
>         //配置Swagger的Bean实例
>         @Bean
>         public Docket docket(Environment environment){
>          
>     
>             //设置要显示的swagger环境
>             Profiles profiles = Profiles.of("dev","test","prod");
>     
>             //通过environment.acceptsProfiles()判断项目环境
>             boolean flag = environment.acceptsProfiles(profiles);
>     
>             return new Docket(DocumentationType.SWAGGER_2)
>                     .apiInfo(apiInfo())
>                     //API文档分组
>                     .groupName("wei")
>                     //是否启用swagger默认true
>                     .enable(flag)
>                     .select()
>                     .apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
>                     .build();
>         }
>     
>         //配置Swagger信息apiInfo
>         private ApiInfo apiInfo(){
>          
>     
>             //作者信息
>             Contact contact = new Contact("wei_shuo", "#", "1096075493@qq.com");
>     
>             return new ApiInfo(
>                     "wei_shuo API文档",
>                     "开源……",
>                     "1.0",
>                     "urn:tos",
>                     contact,
>                     "Apache 2.0",
>                     "http://www.apache.org/licenses/LICENSE-2.0",
>                     new ArrayList()
>             );
>         }
>     
>     }
> 
> ![在这里插入图片描述][7f435cfbabe84f7d8e90d79e0d0725e5.png_pic_center]

#### 实体类扫描 ####

>  *  controller/HelloController.java
> 
>     package com.wei.controller;
>     
>     import com.wei.pojo.User;
>     import org.springframework.web.bind.annotation.GetMapping;
>     import org.springframework.web.bind.annotation.PostMapping;
>     import org.springframework.web.bind.annotation.RequestMapping;
>     import org.springframework.web.bind.annotation.RestController;
>     
>     @RestController
>     public class HelloController {
>          
>     
>         @GetMapping("/hello")
>         public String hello(){
>          
>             return "Hello,Swagger!";
>         }
>     
>         //接口中，返回值存在实体类，就会被扫描到Swagger
>         @PostMapping("/user")
>         public User user(){
>          
>             return new User();
>         }
>     
>     }
> 
>  *  pojo/User.java
> 
> @Api：描述该类的属性和方法
> 
> @ApiModel：描述该类的属性和方法
> 
> @ApiModelProperty：描述该属性或方法的作用、类型、格式、是否必需等信息
> 
>     package com.wei.pojo;
>     
>     import io.swagger.annotations.ApiModel;
>     import io.swagger.annotations.ApiModelProperty;
>     
>     /**
>      * @ClassName User
>      * @Description TODO
>      * @Author wei_shuo
>      * @Date 2023/5/7 10:55
>      * @Version 1.0
>      */
>     
>     @ApiModel("用户实体类")
>     public class User {
>          
>         @ApiModelProperty("用户名")
>         public String username;
>         @ApiModelProperty("密码")
>         public String password;
>     
>     }

>  *  controller/HelloController.java
> 
>     package com.wei.controller;
>     
>     import com.wei.pojo.User;
>     import io.swagger.annotations.Api;
>     import io.swagger.annotations.ApiOperation;
>     import io.swagger.annotations.ApiParam;
>     import org.springframework.web.bind.annotation.GetMapping;
>     import org.springframework.web.bind.annotation.PostMapping;
>     import org.springframework.web.bind.annotation.RestController;
>     
>     @Api(tags = "Hello控制类")
>     @RestController
>     public class HelloController {
>          
>     
>         @GetMapping("/hello")
>         public String hello() {
>          
>             return "Hello,Swagger!";
>         }
>     
>         //接口中，返回值存在实体类，就会被扫描到Swagger
>         @PostMapping("/user")
>         public User user() {
>          
>             return new User();
>         }
>     
>         @ApiOperation("Test控制类")
>         @GetMapping("/test")
>         public String test(@ApiParam("用户名") String username) {
>          
>             return "Hello" + username;
>         }
>     }
> 
> ![在这里插入图片描述][a4c8aa84bac34b7aa7a06cd103c184ce.png_pic_center]

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

> 🌼 结语：创作不易，如果觉得博主的文章赏心悦目，还请——`点赞`👍`收藏`⭐️`评论`📝

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

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

[acb8a7e0bf334001af9f95d515c4f452.gif_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/c19d8c52a09b401aa1df17df8473e960.gif
[wei_shuo]: https://blog.csdn.net/weixin_62765017
[wei_shuo 1]: https://bbs.csdn.net/forums/wei_shuo_study
[95cfb857bba340c48d056321f0ed2473.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/2e15065badfb4a649edcb271ce0b3948.png
[b5e1917201aa40d2b44d8b6563cbb0a0.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/a5f4eeb36ad94972840fc126b778b6ea.png
[34ac1894217644fe8d3e70abef0f1229.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/e13e605699944277ab66f7d1f8440ee9.png
[7f435cfbabe84f7d8e90d79e0d0725e5.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/b3c14848dbdb49638a2579dda0ea5c95.png
[a4c8aa84bac34b7aa7a06cd103c184ce.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/c3d02057d93147a395ae71f1b6307e6d.png
[d3ab6ddb82c2490abc1a7836a1dc557c.gif_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/22/e83289297b2242baaa634078eded56e3.gif