SpringBoot整合OpenApi的实践 SpringBoot整合OpenApi的实践

SpringBoot整合OpenApi

OpenAPI依赖
编写配置类
改造优化
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依赖

【SpringBoot整合OpenApi的实践】引入OpenApi依赖

io.springfoxspringfox-boot-starter3.0.0

编写配置类

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

@EnableOpenApi@Configurationpublic class OpenApiConfiguration {@Beanpublic 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@EnableOpenApipublic class OpenApiConfiguration {@Resourceprivate SwaggerProperties swaggerProperties; @Beanpublic 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: truetitle: 演示OpenAPIdescription: 演示OpenAPIbase-package: com.example.controller

OpenAPI常用注解介绍

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

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

@Data@ApiModel("用户信息")public class UserVO {@ApiModelProperty(value = "https://www.it610.com/article/用户id", required = true, example = "asdf124")private String userId; @ApiModelProperty(value = "https://www.it610.com/article/用户名称", required = true)private String username; @ApiModelProperty(value = "https://www.it610.com/article/用户年龄")private Integer age; }

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

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

@RequestMapping("user")@RestController@Api(tags = "用户中心")public class UserController {@ApiOperation("用户注册")@PostMappingpublic R register(@RequestBody UserVO userVO) {// todo return R.ok(); }@ApiOperation("通过Id获取用户信息")@GetMappingpublic R userInfo(@ApiParam(value = "https://www.it610.com/article/用户id",required = true) @RequestParam String userId) {// todoreturn R.ok(new UserVO()); }}

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