SpringBoot整合OpenApi的实践

SpringBoot整合OpenApi的实践

目录SpringBoot整合OpenApiOpenAPI依赖编写配置类改造优化OpenAPI常用注解介绍实体类controller类演示

网上经常可以看到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依赖

io.springfox

springfox-boot-starter

3.0.0

编写配置类

编写配置类，并手动装配@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 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 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 = "asdfhttp://124")

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 register(@RequestBody UserVO userVO) {

// todo

return R.ok();

}

@ApiOperation("通过Id获取用户信息")

@GetMapping

public R userInfo(@ApiParam(value = "用户id",required = true) @RequestParam String userId) {

// todo

return R.ok(new UserVO());

}

}

演示

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

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。