Springboot整合Swagger2.0、3.0

最新推荐文章于 2024-06-03 08:30:00 发布
最新推荐文章于 2024-06-03 08:30:00 发布
阅读量1.1k 收藏 4
点赞数
分类专栏： # Springboot企业级开发 文章标签： spring boot postman java
本文为博主原创文章，未经博主允许不得转载。
本文链接：https://blog.csdn.net/qq_34491508/article/details/115678349
版权

目录

概述

特点

Swagger2.0

基本使用

Swagger2 配置

配置API分组

其他ui

创建接口

二、Swagger3.0

依赖

支持 OpenAPI

接口地址

注解

概述

Swagger解决什么问题？

1、自动生成REST API 文档（替换了文档方式）

2、在线可调试后端接口（替换postman方式）

特点

  • 号称世界上最流行的API框架

  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

  • 直接运行，在线测试API

  • 支持多种语言 （如：Java，PHP等）

  • 官网：https://swagger.io/

Swagger2.0

基本使用

加入依赖

<dependencies>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

编写HelloController，测试确保运行成功！

访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面

Swagger2 配置

Swagger2 的配置也是比较容易的，在项目创建成功之后，只需要开发者自己提供一个 Docket 的 Bean 即可，如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                //是否启用 正式环境改为false
                .enable(true)
                //基本信息配置
                .apiInfo(new ApiInfoBuilder()
                        .title("数字车间API文档")
                        .description("面朝大海 春暖花开")
                        .version("v1.0")
                        .license("apache 2.0")
                        .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0.html")
                        .contact(new Contact("奥里给", "https://swagger.io/", "https://swagger.io/"))
                        .build())
                /*
                any() // 扫描所有，项目中的所有接口都会被扫描到
                none() // 不扫描接口
                通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                withMethodAnnotation(final Class<? extends Annotation> annotation)
                通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                withClassAnnotation(final Class<? extends Annotation> annotation)
                basePackage(final String basePackage) // 根据包路径扫描接口
                * */
                .select()
                .apis(RequestHandlerSelectors.basePackage(" com.bim.yanchang.controller"))
                /*
                配置接口扫描过滤
                any() // 任何请求都扫描
                none() // 任何请求都不扫描
                regex(final String pathRegex) // 通过正则表达式控制
                ant(final String antPattern) // 通过ant()控制
                 */
                .paths(PathSelectors.ant("/user/**"))
                .build();
    }
}

如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

如此，Swagger2 就算配置成功了，非常方便。

此时启动项目，输入 http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：

配置API分组

1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .groupName("hello") // 配置分组
        // 省略配置....
}

2、重启项目查看分组

3、如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

4、重启项目查看即可

案例

方案1：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestADXApi(Environment environment) {
        Profiles of = Profiles.of("dev","sit", "prd", "pre");
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .groupName("a模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.a.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createRestSSPApi(Environment environment) {
        Profiles of = Profiles.of("dev","sit", "prd", "pre");
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .groupName("b模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.b.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createRestADSApi(Environment environment) {
        Profiles of = Profiles.of("dev","sit", "prd", "pre");
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .groupName("c模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.c.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createRestSystemApi(Environment environment) {
        Profiles of = Profiles.of("dev","sit", "prd", "pre");
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .groupName("d模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.d.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    @Bean
    public Docket createRestFlowmApi(Environment environment) {
        Profiles of = Profiles.of("dev","sit", "prd", "pre");
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .groupName("e模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.e.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createGameleyDmpApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("f模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.f.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("管理后台接口")
                .description("管理后台接口")
                .version("1.0")
                .build();
    }

}

方案2：
@Configuration
@EnableSwagger2
@Profile({"dev","pre"})
public class SwaggerConfig {
    @Bean
    public Docket createGameleyDmpApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("a模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.a.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    @Bean
    public Docket createGameleyTopOnApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo2())
                .groupName("b模块接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.b.controller"))
                .paths(PathSelectors.any())
                .build();
    }

  

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("管理后台a模块接口")
                .description("管理后台接口")
                .version("1.0")
                .build();
    }
    private ApiInfo apiInfo2() {
        return new ApiInfoBuilder()
                .title("接口")
                .description("管理后台b模块接口")
                .version("1.0")
                .build();
    }
}

其他ui

1、默认的   访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui  访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

3、Layui-ui   访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

4、mg-ui   访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

创建接口

接下来就是创建接口了

@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping("/user")
public class UserController {
    @PostMapping("/")
    @ApiOperation("添加用户的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
            @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)
    })
    public RespBean addUser(String username, @RequestParam(required = true) String address) {
        return new RespBean();
    }
    @GetMapping("/")
    @ApiOperation("根据id查询用户的接口")
    @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true)
    public User getUserById(@PathVariable Integer id) {
        User user = new User();
        user.setId(id);
        return user;
    }
    @PutMapping("/{id}")
    @ApiOperation("根据id更新用户的接口")
    public User updateUserById(@RequestBody User user) {
        return user;
    }
}

注解说明：

@Api 注解可以用来标记当前 Controller 的功能。
@ApiOperation 注解用来标记一个方法的作用。
@ApiImplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
需要注意的是，@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger2 框架内必填，抛弃了 Swagger2 ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略。
如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：
 

@ApiModel
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "用户地址")
    private String address;
    //getter/setter
}

刷新刚刚打开的页面，可以看到如下效果：

可以看到，所有的接口这里都列出来了，包括接口请求方式，接口地址以及接口的名字等

二、Swagger3.0

依赖

这两个，一个用来生成接口文档（JSON 数据），另一个用来展示将 JSON 可视化。

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

在 3.0 版本中，我们不需要这么麻烦了，一个 starter 就可以搞定：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

和 Spring Boot 中的其他 starter 一样，springfox-boot-starter 依赖可以实现零配置以及自动配置支持。也就是说，如果你没有其他特殊需求，加一个这个依赖就行了，接口文档就自动生成了。

支持 OpenAPI

什么是 OpenAPI？

OpenAPI 规范其实就是以前的 Swagger 规范，它是一种 REST API 的描述格式，通过既定的规范来描述文档接口，它是业界真正的 API 文档标准，可以通过 YAML 或者 JSON 来描述。它包括如下内容：

  • 接口（/users）和每个接口的操作（GET /users，POST /users）
  • 输入参数和响应内容
  • 认证方法
  • 一些必要的联系信息、license 等。

关于 OpenAPI 的更多内容，感兴趣的小伙伴可以在 GitHub 上查看：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

接口地址

3.0 中的接口地址也和之前有所不同，以前在 2.9.2 中我们主要访问两个地址：

现在在 3.0 中，这两个地址也发生了变化：

特别是文档页面地址，如果用了 3.0，而去访问之前的页面，会报 404。

注解

旧的注解还可以继续使用，不过在 3.0 中还提供了一些其他注解。

例如我们可以使用 @EnableOpenApi 代替以前旧版本中的 @EnableSwagger2。

但是实际使用中，@EnableOpenApi 注解的功能不明显，加不加都行。翻了下源码，@EnableOpenApi 注解主要功能是为了导入 OpenApiDocumentationConfiguration 配置类，如下：

1
2
3
4
5
6

@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)
@Target(value = {java.lang.annotation.ElementType.TYPE})
@Documented
@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi {
}

自动化配置类 OpenApiAutoConfiguration，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

@Configuration
@EnableConfigurationProperties(SpringfoxConfigurationProperties.class)
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
@Import({
    OpenApiDocumentationConfiguration.class,
    SpringDataRestConfiguration.class,
    BeanValidatorPluginsConfiguration.class,
    Swagger2DocumentationConfiguration.class,
    SwaggerUiWebFluxConfiguration.class,
    SwaggerUiWebMvcConfiguration.class
})
@AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class,
    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class })
public class OpenApiAutoConfiguration {

}

可以看到，自动化配置类里边也导入了 OpenApiDocumentationConfiguration。

所以在正常情况下，实际上不需要添加 @EnableOpenApi 注解。

根据 OpenApiAutoConfiguration 上的 @ConditionalOnProperty 条件注解中的定义，我们发现，如果在 application.properties 中设置 springfox.documentation.enabled=false，即关闭了 swagger 功能，此时自动化配置类就不执行了，这个时候可以通过 @EnableOpenApi 注解导入 OpenApiDocumentationConfiguration 配置类。技术上来说逻辑是这样，不过应用中暂未发现这样的需求（即在 application.properties 中关闭 swagger，再通过 @EnableOpenApi 注解开启）。

另外，以前我们用的 @ApiResponses/@ApiResponse 注解，在 3.0 中名字没变，但是所在的包变

另外，我们之前用的 @ApiOperation 注解在 3.0 中可以使用 @Operation 代替。

另外还有一些新注解如 @Parameter、Parameters、@Schema 等

参考地址：Swagger3.0，你所不知道的新变化！ - 江南一点雨

程序三两行
关注
  • 0
    点赞
  • 踩
  • 4
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
专栏目录
（一）springboot整合之swagger2（详细）
weixin_58993861的博客
02-07 1万+
1.新建springboot项目 2.引入maven依赖 <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version> 2.9.2</version>
SpringBoot整合Swagger3.0
qq_51569224的博客
07-18 2420
SpringBoot整合Swagger3.0
springboot整合swagger2
m0_74295724的博客
04-17 1361
springboot整合swagger2
Spring Boot 开发 -- swagger3.0 集成
最新发布
dazhong2012的专栏
06-03 821
*** Swagger2的接口配置*//*** 是否开启swagger*//*** 创建API*/@Bean// 是否启用Swagger// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）// 设置哪些接口暴露给Swagger展示.select()// 扫描所有有注解的api，用这种方式更灵活//扫描所有.build()// 支持的通讯协议集合/* 设置安全模式，swagger可以设置访问token *//*** 支持的通讯协议集合。
SpringBoot 集成 Swagger2
asksl的博客
11-29 790
SpringBoot 集成 Swagger2
Spring Boot整合Swagger2详解
Charge8的博客
11-29 8338
Spring Boot整合Swagger2详解
springboot集成Swagger3.0
m0_50959444的博客
11-23 351
1、默认已经创建好Springboot 项目 2、引入swagger3.0依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 3、创建swagger配置类 package com.yo
springboot 整合swagger2.0支持API注释显示
12-02
SpringBoot整合Swagger2.0是为了实现API文档的自动化生成与管理，这在现代微服务架构中尤为重要，因为清晰、详尽的API文档可以帮助开发者更好地理解和使用接口。Swagger2.0是一个强大的工具，它遵循OpenAPI规范，...
SpringBoot整合Swagger3生成接口文档过程解析
08-18
SpringBoot整合Swagger3生成接口文档过程解析 SpringBoot整合Swagger3生成接口文档过程解析是当前项目中非常重要的一部分，在前后端分离的项目中，接口文档的存在十分重要。 Swagger是一个自动生成接口文档的工具...
springboot整合swagger2实例
02-28
SpringBoot整合Swagger2实例详解 在现代Web开发中，API文档的重要性不言而喻，它为开发者提供了清晰的接口说明，使得开发、测试和维护工作更加高效。Swagger2是一款流行的API文档工具，它能自动生成RESTful API的...
springBoot整合Swagger项目例子
01-22
SpringBoot整合Swagger项目是一个实用的例子，它展示了如何在SpringBoot应用程序中集成Swagger，以便于创建API文档和进行接口测试。Swagger是一个强大的工具，用于设计、构建、文档化和使用RESTful Web服务。在这个...
SpringBoot整合Swagger2代码实例
08-24
SpringBoot整合Swagger2代码实例 SpringBoot是一款流行的Java框架，用于构建基于Web的应用程序，而Swagger2是一个流行的API文档工具，用于生成RESTful API的文档。将SpringBoot与Swagger2整合，可以生成详细的API...
SpringBoot 整合Swagger2
小钟不想敲代码
08-11 7257
SpringBoot 整合Swagger2
springfox-swagger2 3.0.0使用教程
热门推荐
fygkchina的专栏
10-27 1万+
最近 SpringFox 3.0.0 发布了，距离上一次大版本2.9.2足足有2年多时间了。可能看到这个名字，很多读者会有点陌生。但是，只要给大家看一下这两个依赖，你就知道了！ <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version&g
Springboot整合Swagger2（3.0.0版本）
分享式获得也是一种学习的态度
05-26 2571
swagger2是一个基于OpenAPI（OpenAPI Specification，OAS）构建的开源工具，提供对REST API文档的一些有效帮助。简而言之就是将项目中的controller类和方法通过注解方式生成文档展现出来。swagger codegen：通过OpenApi规范定义任何api生成服务器存根和客户端sdk来简化构建过程swagger editor： 浏览器编辑器，用来编写OpenApi规范swagger ui： 可以在浏览器上查看并操作REST API。
Swagger2.0和resful规范
habazhu1110的专栏
10-26 1524
提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档 文章目录 前言 一、pandas是什么？ 二、使用步骤 1.引入库 2.读入数据 总结 前言 面对层出不穷的语言，java为何屹立多年不倒。论简单不如python，性能上不如go，为什么大规模开发依然首选java。作为一名架构师，我深刻感悟着java之美。java的美和优势在于规范，虽然python，go也都有面向对象的设计和支持，但是在实践中往往都是面向过程。虽然都有各种代码要求但是在实践中往往都是随心所
Swagger 2.0 规范 详解
RichardGeek的博客
06-14 3585
Swagger 2.0 规范 详解
springboot3.0和2.0区别
01-11
Spring Boot 3.0和2.0在以下几个方面有所区别： 1. Java版本：Spring Boot 3.0需要使用Java 11或更高版本，而Spring Boot 2.0则支持Java 8及以上版本。 2. Spring Framework版本：Spring Boot 3.0使用的是Spring Framework 6.0版本，而Spring Boot 2.0使用的是Spring Framework 5.0版本。 3. 模块化支持：Spring Boot 3.0引入了Java模块化系统（Java Platform Module System，JPMS）的支持，可以更好地管理和组织项目的依赖关系。 4. Web框架：Spring Boot 3.0在Web框架方面进行了改进和增强，提供了更多的功能和选项，使得开发Web应用更加方便和高效。 5. 数据库访问：Spring Boot 3.0对数据库访问进行了优化，提供了更多的数据库支持和集成选项，使得与数据库的交互更加简单和灵活。 需要根据您的项目需求和偏好来决定是否升级到Spring Boot 3.0。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

程序三两行

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值