个人中心
gpt4 book ai didi

SpringBoot整合OpenApi的实践

转载 作者：qq735679552 更新时间：2022-09-27 22:32:09 27 4
gpt4 key购买 nike

CFSDN坚持开源创造价值，我们致力于搭建一个资源共享平台，让每一个IT人在这里找到属于你的精彩世界.

这篇CFSDN的博客文章SpringBoot整合OpenApi的实践由作者收集整理，如果你对这篇文章有兴趣，记得点赞哟.

网上经常可以看到OpenAPI和Swagger相关的词汇，总是傻傻分不清，这里先简单介绍一下Swagger个OpenAPI的联系.

OpenAPI是规范；Swagger是实现规范的工具.

OpenAPI 3.0是该规范的第一个正式版本，因为它是由SmartBear Software捐赠给OpenAPI Initiative，并在2015年从Swagger规范重命名为OpenAPI规范.

OpenAPI是规范的正式名称。该规范的开发是由OpenAPI Initiative推动的，该倡议涉及更多来自技术领域不同领域的30个组织-包括Microsoft，Google，IBM和CapitalOne.

领导Swagger工具开发的公司Smartbear Software也是OpenAPI Initiative的成员，帮助领导了规范的发展.

SpringBoot整合OpenApi

确保SpringBoot版本在2.x级以上.

OpenAPI依赖

引入OpenApi依赖 。

?
1
2
3
4
5
< dependency >
     < groupId >io.springfox</ groupId >
     < artifactId >springfox-boot-starter</ artifactId >
     < version >3.0.0</ version >
</ dependency >

编写配置类

编写配置类，并手动装配@EnableOpenApi 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@EnableOpenApi
@Configuration
public class OpenApiConfiguration {
 
     @Bean
     public Docket createRestApi() {
         return new Docket(DocumentationType.OAS_30)
                 .apiInfo(apiInfo())
                 .select()
                 .apis(apis())
                 .paths(PathSelectors.any())
                 .build()
                 .enable( true );
     }
 
     private ApiInfo apiInfo() {
         return new ApiInfoBuilder()
                 .title( "项目名称" )
                 .description( "项目描述" )
                 .termsOfServiceUrl( "项目地址" )
                 .version( "API版本" )
                 .license( "公司的license" )
                 .licenseUrl( "公司的license地址" )
                 .build();
     }
 
     private Predicate<RequestHandler> apis() {
         return RequestHandlerSelectors.basePackage( "controller包的路径" );
     }
}

到这里SpringBoot就整合OpenAPI成功了。需要一提的是，OpenAPI不仅可以通过扫描controller包的路径生成OpenAPI，也可以通过扫描@ApiOperation来生成OpenAPI.

改造优化

上面的示例通过硬编码的形式，所以无法进行代码的复用，而且每次更新配置的时候，都需要更改代码，比如我们的项目在开发或者测试环境时，我们希望能正常使用OpenAPI但是在生产环境需要禁用OpenAPI。 在工程学的角度，常用的做法是尽量通过更改配置的形式，问不是更改代码。基于此，我们可以借助SpringBoot的配置功能，对上述代码进行改造.

新增OpenApi配置类 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@Data
@Component
@ConfigurationProperties (prefix = "example.web.swagger" )
public class SwaggerProperties {
     /**
      * 是否swagger3启用，默认不启用
      */
     private Boolean enable = false ;
     /**
      * 扫描包路径，可以不指定，系统会通过自动扫描{@link io.swagger.annotations.ApiOperation}
      */
     private String basePackage;
     /**
      * 标题
      */
     private String title;
     /**
      * 应用描述
      */
     private String description;
     /**
      * 服务地址
      */
     private String serviceUrl;
     /**
      * 版本，默认V1.0.0
      */
     private String version = "V1.0.0" ;
     /**
      * license
      */
     private String license;
     /**
      * licenseUrl
      */
     private String licenseUrl;
}

配置替换硬编码 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
@Slf4j
@Configuration
@EnableOpenApi
public class OpenApiConfiguration {
 
     @Resource
     private SwaggerProperties swaggerProperties;
 
     @Bean
     public Docket createRestApi() {
         return new Docket(DocumentationType.OAS_30)
                 .apiInfo(apiInfo())
                 .select()
                 .apis(apis())
                 .paths(PathSelectors.any())
                 .build()
                 .enable(isEnable());
     }
 
     private Boolean isEnable() {
         Boolean enable = swaggerProperties.getEnable();
         if (enable) {
             log.info( "\nEnable Swagger3..." );
         }
         return enable;
     }
 
     private ApiInfo apiInfo() {
         return new ApiInfoBuilder()
                 .title(swaggerProperties.getTitle())
                 .description(swaggerProperties.getDescription())
                 .termsOfServiceUrl(swaggerProperties.getServiceUrl())
                 .version(swaggerProperties.getVersion())
                 .license(swaggerProperties.getLicense())
                 .licenseUrl(swaggerProperties.getLicenseUrl())
                 .build();
     }
 
     private Predicate<RequestHandler> apis() {
         String basePackage = swaggerProperties.getBasePackage();
         // 默认通过扫描`ApiOperation`如果配置了包扫描路径，使用配置的包扫描路径
         return Strings.isNullOrEmpty(basePackage) ? withMethodAnnotation(ApiOperation. class ) : basePackage(basePackage);
     }
}

通过这样的简单改造后，我们就可以完全通过配置文件的形式配置OpenApi 。

示例配置 。

?
1
2
3
4
5
6
7
example:
   web:
     swagger:
       enable: true
       title: 演示OpenAPI
       description: 演示OpenAPI
       base-package: com.example.controller

OpenAPI常用注解介绍

这里通过使用代码演示注解的使用 。

实体类

需要在用户的VO实体类标注@ApiModel并说明该类的作用， 属性上通过@ApiModelProperty解析属性的作用，并通过required值约定该属性是否可以为空 可以通过example说明该属性的用例值 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
@Data
@ApiModel ( "用户信息" )
public class UserVO {
 
     @ApiModelProperty (value = "用户id" , required = true , example = "asdf124" )
     private String userId;
 
     @ApiModelProperty (value = "用户名称" , required = true )
     private String username;
 
     @ApiModelProperty (value = "用户年龄" )
     private Integer age;
}

controller类

这里主要通过用户注册和用户信息接口演示.

在配上通过@Api标注该类的功能；通过@ApiOperation说明接口的功能，如果传入的数据不是实体类，而是一个基本数据类型，可以通过@ApiParam解释参数的作用 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@RequestMapping ( "user" )
@RestController
@Api (tags = "用户中心" )
public class UserController {
 
     @ApiOperation ( "用户注册" )
     @PostMapping
     public R<Void> register( @RequestBody UserVO userVO) {
         // todo
         return R.ok();
     }
 
     @ApiOperation ( "通过Id获取用户信息" )
     @GetMapping
     public R<UserVO> userInfo( @ApiParam (value = "用户id" ,required = true ) @RequestParam String userId) {
         // todo
         return R.ok( new UserVO());
     }
}

演示

启动项目，通过访问IP:PORT/swagger-ui/index.html即可看到swagger界面 。

SpringBoot整合OpenApi的实践

到此这篇关于SpringBoot整合OpenApi的实践的文章就介绍到这了,更多相关SpringBoot整合OpenApi内容请搜索我以前的文章或继续浏览下面的相关文章希望大家以后多多支持我！ 。

原文链接：https://juejin.cn/post/7000351567677227045 。

最后此篇关于SpringBoot整合OpenApi的实践的文章就讲到这里了,如果你想了解更多关于SpringBoot整合OpenApi的实践的内容请搜索CFSDN的文章或继续浏览相关文章，希望大家以后支持我的博客！ 。

27 4 0
文章推荐： 如何开发基于Netty的HTTP/HTTPS应用程序
文章推荐： C++实现单张图片读取和保存
文章推荐： java对象数组实现学生信息管理系统
文章推荐： SpringBoot Scheduling定时任务的示例代码
qq735679552
个人简介

我是一名优秀的程序员,十分优秀！

滴滴打车优惠券免费领取
滴滴打车优惠券
全站热门文章
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com