java 单机接口限流处理方案
430
2022-06-06
网上经常可以看到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版本在2.x级以上。
引入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
这里通过使用代码演示注解的使用
需要在用户的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; }
这里主要通过用户注册和用户信息接口演示。
在配上通过@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界面
版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。
发表评论
暂时没有评论,来抢沙发吧~