亲宝软件园·资讯

展开

SpringBoot整合OpenApi SpringBoot整合OpenApi的实践

范闲 人气:10
想了解SpringBoot整合OpenApi的实践的相关内容吗,范闲在本文为您仔细讲解SpringBoot整合OpenApi的相关知识和一些Code实例,欢迎阅读和指正,我们先划重点: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依赖

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

加载全部内容

相关教程
猜你喜欢
用户评论