位置：首页>> 软件编程>> java编程>> SpringBoot整合OpenApi的实践

SpringBoot整合OpenApi的实践

作者：范闲　　发布时间：2023-08-03 11:59:55　

标签：SpringBoot,整合,OpenApi

SpringBoot整合OpenApi

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

OpenAPI依赖

引入OpenApi依赖

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

编写配置类

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

@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配置类

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

配置替换硬编码

@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

示例配置

example:
web:
swagger:
enable: true
title: 演示OpenAPI
description: 演示OpenAPI
base-package: com.example.controller

OpenAPI常用注解介绍

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

实体类

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

@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解释参数的作用

@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界面

来源：https://juejin.cn/post/7000351567677227045

投稿

SpringBoot整合OpenApi的实践

目录