AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

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

2023-12-18 96
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： SpringBoot原理分析 | 开源框架：Swagger集成

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

  • 依赖导入
<!--springfox-boot-starter-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!--springfox-swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!--springfox-swagger-ui-->
        <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

配置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()
        );
    }
}
  • 浏览器运行

配置扫描接口

  • 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的开发，测试，发布

  • 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()
        );
    }
}

实体类扫描

  • 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;
    }
}

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

文章标签：
API
Java
开发工具
JavaScript
测试技术
关键词：
Spring Boot原理
Spring Boot分析
Swagger springboot
集成springboot
集成swagger
wei_shuo
目录
相关文章
蓝易云
|
14天前
|
Java 关系型数据库 MySQL
SpringBoot 通过集成 Flink CDC 来实时追踪 MySql 数据变动
通过详细的步骤和示例代码，您可以在 SpringBoot 项目中成功集成 Flink CDC，并实时追踪 MySQL 数据库的变动。
蓝易云
119 43
蓝易云
|
16天前
|
监控 前端开发 Java
SpringBoot集成Tomcat、DispatcherServlet
通过这些配置，您可以充分利用 Spring Boot 内置的功能，快速构建和优化您的 Web 应用。
蓝易云
48 21
智物科技库
|
29天前
|
Dart 前端开发 JavaScript
springboot自动配置原理
Spring Boot 自动配置原理：通过 `@EnableAutoConfiguration` 开启自动配置，扫描 `META-INF/spring.factories` 下的配置类，省去手动编写配置文件。使用 `@ConditionalXXX` 注解判断配置类是否生效，导入对应的 starter 后自动配置生效。通过 `@EnableConfigurationProperties` 加载配置属性，默认值与配置文件中的值结合使用。总结来说，Spring Boot 通过这些机制简化了开发配置流程，提升了开发效率。
智物科技库
61 17
springboot自动配置原理
潜意识Java
|
30天前
|
Java 应用服务中间件 API
【潜意识Java】javaee中的SpringBoot在Java 开发中的应用与详细分析
本文介绍了 Spring Boot 的核心概念和使用场景，并通过一个实战项目演示了如何构建一个简单的 RESTful API。
潜意识Java
41 5
大数据文摘
|
1月前
|
XML JavaScript Java
SpringBoot集成Shiro权限+Jwt认证
本文主要描述如何快速基于SpringBoot 2.5.X版本集成Shiro+JWT框架，让大家快速实现无状态登陆和接口权限认证主体框架，具体业务细节未实现，大家按照实际项目补充。
大数据文摘
87 11
蓝易云
|
1月前
|
监控 Java Nacos
使用Spring Boot集成Nacos
通过上述步骤，Spring Boot应用可以成功集成Nacos，利用Nacos的服务发现和配置管理功能来提升微服务架构的灵活性和可维护性。通过这种集成，开发者可以更高效地管理和部署微服务。
蓝易云
208 17
Harry技术
|
1月前
|
缓存 安全 Java
Spring Boot 3 集成 Spring Security + JWT
本文详细介绍了如何使用Spring Boot 3和Spring Security集成JWT，实现前后端分离的安全认证概述了从入门到引入数据库，再到使用JWT的完整流程。列举了项目中用到的关键依赖，如MyBatis-Plus、Hutool等。简要提及了系统配置表、部门表、字典表等表结构。使用Hutool-jwt工具类进行JWT校验。配置忽略路径、禁用CSRF、添加JWT校验过滤器等。实现登录接口，返回token等信息。
Harry技术
369 12
Harry技术
|
1月前
|
存储 安全 Java
Spring Boot 3 集成Spring AOP实现系统日志记录
本文介绍了如何在Spring Boot 3中集成Spring AOP实现系统日志记录功能。通过定义`SysLog`注解和配置相应的AOP切面，可以在方法执行前后自动记录日志信息，包括操作的开始时间、结束时间、请求参数、返回结果、异常信息等，并将这些信息保存到数据库中。此外，还使用了`ThreadLocal`变量来存储每个线程独立的日志数据，确保线程安全。文中还展示了项目实战中的部分代码片段，以及基于Spring Boot 3 + Vue 3构建的快速开发框架的简介与内置功能列表。此框架结合了当前主流技术栈，提供了用户管理、权限控制、接口文档自动生成等多项实用特性。
Harry技术
84 8
蓝染-惣右介
|
2月前
|
Java 数据库连接 Maven
最新版 | 深入剖析SpringBoot3源码——分析自动装配原理（面试常考）
自动装配是现在面试中常考的一道面试题。本文基于最新的 SpringBoot 3.3.3 版本的源码来分析自动装配的原理，并在文未说明了SpringBoot2和SpringBoot3的自动装配源码中区别，以及面试回答的拿分核心话术。
蓝染-惣右介
79 2
最新版 | 深入剖析SpringBoot3源码——分析自动装配原理（面试常考）
智物科技库
|
2月前
|
NoSQL Java Redis
Spring Boot 自动配置机制：从原理到自定义
Spring Boot 的自动配置机制通过 `spring.factories` 文件和 `@EnableAutoConfiguration` 注解，根据类路径中的依赖和条件注解自动配置所需的 Bean，大大简化了开发过程。本文深入探讨了自动配置的原理、条件化配置、自定义自动配置以及实际应用案例，帮助开发者更好地理解和利用这一强大特性。
智物科技库
153 14

热门文章

最新文章

  • 1
    SpringBootWeb篇-入门了解Swagger的具体使用
  • 2
    轻松在本地部署 DeepSeek 蒸馏模型并无缝集成到你的 IDE
  • 3
    百聆：集成Deepseek API及语音技术的开源AI语音对话助手，实时交互延迟低至800ms
  • 4
    LangBot：无缝集成到QQ、微信等消息平台的AI聊天机器人平台
  • 5
    Flink CDC YAML：面向数据集成的 API 设计
  • 6
    AppFlow：无代码部署Dify并集成到企业微信
  • 7
    一键部署开源DeepSeek并集成到企业微信
  • 8
    轻松集成私有化部署Dify文本生成型应用
  • 9
    【11】flutter进行了聊天页面的开发-增加了即时通讯聊天的整体页面和组件-切换-朋友-陌生人-vip开通详细页面-即时通讯sdk准备-直播sdk准备-即时通讯有无UI集成的区别介绍-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草Alex
  • 10
    一键部署开源DeepSeek并集成到钉钉
  • 1
    Springboot使用Redis实现分布式锁
    112
  • 2
    编写SpringBoot的自定义starter包
    36
  • 3
    SpringBoot：SpringBoot通过注解监测Controller接口
    34
  • 4
    SpringBoot-打包&部署
    46
  • 5
    spring boot 启动流程
    53
  • 6
    Springboot静态资源映射及文件映射
    49
  • 7
    SpringBoot 2.0 多图片上传加回显
    21
  • 8
    SpringBoot 通过集成 Flink CDC 来实时追踪 MySql 数据变动
    119
  • 9
    SpringBoot集成Tomcat、DispatcherServlet
    48
  • 10
    springboot怎么使用rides缓存方法的返回值 完整例子
    53

    • 相关课程

    更多
  • 事件总线EventBridge生态集成课程
  • 消息队列 RocketMQ 消息集成
  • 微服务+全栈在线教育实战项目演练（SpringCloud Alibaba+SpringBoot）
  • SpringBoot实战教程
  • SpringBoot快速掌握 - 核心技术
  • SpringBoot快速掌握 - 高级应用

    • 相关电子书

    更多
  • 行业实践：RocketMQ 业务集成典型行业应用和实践
  • Cloud Foundry on Cloud-- 开源PaaS集成技术实现
  • 新零售下的企业供应链集成

    • 相关实验场景

    更多
  • 从零搭建Spring Boot的Hello World
  • 搭建Java Web开发环境
  • 基于 IntelliJ IDEA 插件部署微服务应用
  • Rocketmq-spring入门与实践
  • Spring-cloud-bus-rocketmq入门与实践
  • Spring-cloud-stream-binder-rocketmq入门与实践
    • 下一篇
    阿里云oss简介和如何对接使用