OpenAPI使用（swagger3）

demo見Gitte

一、背景及名詞解釋

OpenAPI是規范的正式名稱。規范的開發工作于2015年啟動，當時SmartBear（負責Swagger工具開發的公司）將Swagger 2.0規范捐贈給了Open API Initiative，該協會由來自技術領域不同領域的30多個組織組成。此后，該規范被重命名為OpenAPI規范。 Swagger 是一個 API文檔維護組織，后來成為了 Open API 標準的主要定義者。現在最新的版本為17年發布的 Swagger3（Open Api3）。 是一個Open API規范實現工具包，由于Swagger工具是由參與創建原始Swagger規范的團隊開發的，因此通常仍將這些工具視為該規范的代名詞。目前可以認為Swagger3就是Open API 3.0 OpenAPI 3.0：2017年7月，Open API Initiative最終發布了OpenAPI Specification 3.0.0。它對2.0規范進行了很多改進。Open API 3.0規范可以用JSON或YAML編寫，并且在記錄RESTful API方面做得很好。同時標志著Swagger2成為過去式。 SpringFox是 spring 社區維護的一個項目（非官方），幫助使用者將 swagger2 集成到 Spring 中。常常用于 Spring 中幫助開發者生成文檔，并可以輕松的在spring boot中使用。截至2020年4月，尚未支持 OpenAPI3 標準。 SpringDoc也是 spring 社區維護的一個項目（非官方），幫助使用者將 swagger3 集成到 Spring 中。 也是用來在 Spring 中幫助開發者生成文檔，并可以輕松的在spring boot中使用

二、整合springdoc-openapi

maven的話，在pom.xml里面去掉springfox，添加如下的openapi依賴。

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.5.2</version>
</dependency>

gradle的話 build.gradle.kts中添加

implementation("org.springdoc:springdoc-openapi-ui:1.5.2")

就這么簡單，文檔就構建完成了，不需要做任何的其他配置。 訪問：http://ip:port/swagger-ui.html

三、將API分組分組展示

配置方法 java:

@Configuration
public class OpenAPIConfig {@Bean
public GroupedOpenApi restApi() {
return GroupedOpenApi.builder()
.group("rest-api")
.pathsToMatch("/rest/**")
.build();
}@Bean
public GroupedOpenApi helloApi() {
return GroupedOpenApi.builder()
.group("hello")
.pathsToMatch("/hello/**")
.build();
}}

kotlin:

@Configuration
class OpenAPIConfig {@Beanfun restApi(): GroupedOpenApi {return GroupedOpenApi.builder().group("rest-api").pathsToMatch("/rest/**").build()}@Beanfun helloApi(): GroupedOpenApi {return GroupedOpenApi.builder().group("hello").pathsToMatch("/hello/**").build()}
}

顯示效果,通過下拉選擇分組，查看組內API

四、使用 swagger3 注解代替 swagger2注解

如果你希望為文檔加上更詳細的中文注釋，使用如下注解（對比Swagger2注解使用方法使用即可）。但是筆者覺得沒有必要學習這東西，意義不大。注意變量、接口命名規范，英文的接口文檔就挺好。 用 swagger 3 的注解（已經在上面maven包引入）代替 swagger 2 的注解，swagger 3 注解的包路徑為io.swagger.v3.oas.annotations。

四、常見問題

api寫入分組后未展示：
解決方法：放入數組后再使用，見這里

---

更多內容指引官網：https://springdoc.org/

總結

以上是生活随笔為你收集整理的OpenAPI使用（swagger3），Kotlin使用swagger3，Java使用swagger3，gradle、Maven使用swagger3的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。