SpringBoot整合OpenApi的實(shí)踐
網(wǎng)上經(jīng)??梢钥吹絆penAPI和Swagger相關(guān)的詞匯,總是傻傻分不清,這里先簡單介紹一下Swagger個(gè)OpenAPI的聯(lián)系。
OpenAPI是規(guī)范;Swagger是實(shí)現(xiàn)規(guī)范的工具。
OpenAPI 3.0是該規(guī)范的第一個(gè)正式版本,因?yàn)樗怯蒘martBear Software捐贈(zèng)給OpenAPI Initiative,并在2015年從Swagger規(guī)范重命名為OpenAPI規(guī)范。
OpenAPI是規(guī)范的正式名稱。該規(guī)范的開發(fā)是由OpenAPI Initiative推動(dòng)的,該倡議涉及更多來自技術(shù)領(lǐng)域不同領(lǐng)域的30個(gè)組織-包括Microsoft,Google,IBM和CapitalOne。
領(lǐng)導(dǎo)Swagger工具開發(fā)的公司Smartbear Software也是OpenAPI Initiative的成員,幫助領(lǐng)導(dǎo)了規(guī)范的發(fā)展。
SpringBoot整合OpenApi
確保SpringBoot版本在2.x級(jí)以上。
OpenAPI依賴
引入OpenApi依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
編寫配置類
編寫配置類,并手動(dòng)裝配@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("項(xiàng)目名稱") .description("項(xiàng)目描述") .termsOfServiceUrl("項(xiàng)目地址") .version("API版本") .license("公司的license") .licenseUrl("公司的license地址") .build(); } private Predicate<RequestHandler> apis() { return RequestHandlerSelectors.basePackage("controller包的路徑"); } }
到這里SpringBoot就整合OpenAPI成功了。需要一提的是,OpenAPI不僅可以通過掃描controller包的路徑生成OpenAPI,也可以通過掃描@ApiOperation來生成OpenAPI。
改造優(yōu)化
上面的示例通過硬編碼的形式,所以無法進(jìn)行代碼的復(fù)用,而且每次更新配置的時(shí)候,都需要更改代碼,比如我們的項(xiàng)目在開發(fā)或者測(cè)試環(huán)境時(shí),我們希望能正常使用OpenAPI但是在生產(chǎn)環(huán)境需要禁用OpenAPI。
在工程學(xué)的角度,常用的做法是盡量通過更改配置的形式,問不是更改代碼。基于此,我們可以借助SpringBoot的配置功能,對(duì)上述代碼進(jìn)行改造。
新增OpenApi配置類
@Data @Component @ConfigurationProperties(prefix = "example.web.swagger") public class SwaggerProperties { /** * 是否swagger3啟用,默認(rèn)不啟用 */ private Boolean enable = false; /** * 掃描包路徑,可以不指定,系統(tǒng)會(huì)通過自動(dòng)掃描{@link io.swagger.annotations.ApiOperation} */ private String basePackage; /** * 標(biāo)題 */ private String title; /** * 應(yīng)用描述 */ private String description; /** * 服務(wù)地址 */ private String serviceUrl; /** * 版本,默認(rèn)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(); // 默認(rèn)通過掃描`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常用注解介紹
這里通過使用代碼演示注解的使用
實(shí)體類
需要在用戶的VO實(shí)體類標(biāo)注@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類
這里主要通過用戶注冊(cè)和用戶信息接口演示。
在配上通過@Api標(biāo)注該類的功能;通過@ApiOperation說明接口的功能,如果傳入的數(shù)據(jù)不是實(shí)體類,而是一個(gè)基本數(shù)據(jù)類型,可以通過@ApiParam解釋參數(shù)的作用
@RequestMapping("user") @RestController @Api(tags = "用戶中心") public class UserController { @ApiOperation("用戶注冊(cè)") @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()); } }
演示
啟動(dòng)項(xiàng)目,通過訪問IP:PORT/swagger-ui/index.html即可看到swagger界面
到此這篇關(guān)于SpringBoot整合OpenApi的實(shí)踐的文章就介紹到這了,更多相關(guān)SpringBoot整合OpenApi內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
減小Maven項(xiàng)目生成的JAR包體積實(shí)現(xiàn)提升運(yùn)維效率
在Maven構(gòu)建Java項(xiàng)目過程中,減小JAR包體積可通過排除不必要的依賴和使依賴jar包獨(dú)立于應(yīng)用jar包來實(shí)現(xiàn),在pom.xml文件中使用<exclusions>標(biāo)簽排除不需要的依賴,有助于顯著降低JAR包大小,此外,將依賴打包到應(yīng)用外,可減少應(yīng)用包的體積2024-10-10springboot aspect通過@annotation進(jìn)行攔截的實(shí)例代碼詳解
這篇文章主要介紹了springboot aspect通過@annotation進(jìn)行攔截的方法,本文通過實(shí)例代碼給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2020-08-08使用Jmeter進(jìn)行http接口測(cè)試的實(shí)踐
本文主要針對(duì)http接口進(jìn)行測(cè)試,使用Jmeter工具實(shí)現(xiàn)。文中通過示例代碼介紹的非常詳細(xì),具有一定的參考價(jià)值,感興趣的小伙伴們可以參考一下2021-11-11SpringBoot中的yaml語法及靜態(tài)資源訪問問題
這篇文章主要介紹了SpringBoot中的yaml語法及靜態(tài)資源訪問問題,本文給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2021-07-07詳解Spring boot+CXF開發(fā)WebService Demo
這篇文章主要介紹了詳解Spring boot+CXF開發(fā)WebService Demo,非常具有實(shí)用價(jià)值,需要的朋友可以參考下2017-05-05JpaRepository?實(shí)現(xiàn)簡單條件查詢
這篇文章主要介紹了JpaRepository?實(shí)現(xiàn)簡單條件查詢,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2021-11-11Java代理模式之靜態(tài)代理與動(dòng)態(tài)代理的區(qū)別及優(yōu)缺點(diǎn)
代理模式是一種常用的設(shè)計(jì)模式,它允許通過引入一個(gè)代理對(duì)象來控制對(duì)目標(biāo)對(duì)象的訪問,在Java中,代理模式被廣泛應(yīng)用,它可以提供額外的功能,如權(quán)限檢查、緩存、日志記錄等,本文將介紹靜態(tài)代理與動(dòng)態(tài)代理的區(qū)別及優(yōu)缺點(diǎn),需要的朋友可以參考下2023-06-06Java springboot 配置文件與多環(huán)境配置與運(yùn)行優(yōu)先級(jí)
這篇文章主要介紹了Java springboot如何配置文件,進(jìn)行多環(huán)境配置,以及運(yùn)行優(yōu)先級(jí),感興趣的小伙伴可以借鑒一下2023-04-04