wagger 最初作為一套規范而問世,后來在 2015 年捐贈給Linux基金會后演變為 OpenAPI 規范(OAS)。這次轉變標志著 API 文檔編寫和互操作性的一次進步,使其向 OpenAPI 3.0 過渡。在現今的行業討論中,提到 Swagger 通常指的是 SmartBear Software 開發的一套用于實現 OpenAPI 規范的工具。這套工具包括開源、免費和商業工具的組合,支持 API 生命周期的各個開發階段。
使用 Swagger 工具的核心在于采用設計優先的原則,把生成 API 文檔視為開發過程的基石。開發者可以根據自己的偏好選擇方法:一些人偏好使用 Swagger Editor 在線創建 API 文檔,而另一些人則偏好編寫代碼時注釋,讓文檔自動生成。這兩種方法都為簡化和優化開發過程提供了路徑。
其中,Spring Boot 項目的集成已表現出良好的適應性,Springfox和Springdoc作為領先的開源庫促進了這一整合。
Springfox 作為 Swagger 的 Java 實現,幫助生成兼容 Swagger 2.0 規范的 API 文檔。它通過一系列注解為開發者提供了生成相應 API 文檔的能力。此外,Springfox 還提供了可擴展接口,允許定制文檔生成過程以滿足特殊需求。盡管它因支持 Swagger 2 規范而被廣泛使用,但更新速度緩慢和與新版本 Spring Boot 的兼容問題一直是人們關心的問題。
與此同時,Springdoc 因其與 Spring Boot 的深度集成以及支持 OpenAPI 3.0 規范而脫穎而出。它涵蓋了更廣泛的Spring項目,包括 Spring WebMvc、Spring WebFlux、Spring Data Rest 和 Spring Security。以快速更新和生成 OpenAPI 3.0 規范文檔而聞名,Springdoc 也為用戶提供了自定義文檔生成過程的能力,盡管目前支持的插件較少。
springdoc-openapi Java 庫為 Spring Boot 應用中自動化生成 API 文檔提供了創新解決方案。它通過審查應用的 Spring 配置、類結構和注釋來推斷 API 語義,產生格式化的 JSON/YAML 和 HTML 文檔。
通過訪問http://server:port/context-path/swagger-ui.html來查看生成的 Swagger 文檔。
雖然springdoc-openapi為 API 文檔提供了無與倫比的支持,但將其與 Apifox 整合為分享和同步 API 細節提供了一個吸引人的途徑。Apifox 提供了一個全面的平臺,支持 API 設計、文檔、測試和協作功能,能夠自動解析代碼注釋并從 Javadoc、KDoc 和 ScalaDoc 生成 API 文檔。通過使用 IntelliJ IDEA 的 Apifox Helper 插件,開發人員可以在不離開 IDE 的情況下與 Apifox 項目同步他們的文檔。此外,Apifox 通過其直觀的UI豐富了 API 管理體驗,支持從 IDEA 直接啟動內部測試和導出文檔。
對于希望提升 API 文檔和協作工作流的開發人員,采用 Apifox 與 Springdoc-openapi 可能成為改變游戲規則的策略。
Spring Boot作為當前最為流行的Java web開發腳手架,越來越多的開發者選擇用其來構建企業級的RESTFul API接口。這些接口不但會服務于傳統的web端(b/s),也會服務于移動端。在實際開發過程中,這些接口還要提供給開發測試進行相關的白盒測試,那么勢必存在如何在多人協作中共享和及時更新API開發接口文檔的問題。
使用 Swagger 集成文檔具有以下幾個優勢:
接下來,我們通過Spring Boot來整合Swagger實現在線API文檔的功能,本文用的是SpringFox Swagger2,版本2.9.2(最新版本是3.0.0,但是在我測試是swagger-ui.html頁面一直出不來,在https://mvnrepository.com/上也可以看到,2.9.2是目前使用最多的版本)
我用的開發工具是IDEA,通過IDEA快速創建一個Spring Boot工程,創建時,只需勾選web依賴選項就成,不勾選也沒關系,后面在pom.xml中配置也是一樣的。注意創建工程時,工程名稱都要是小寫。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
添加一個swagger 配置類,在工程下新建 config 包并添加一個 SwaggerConfig 配置類SwaggerConfig.java。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("在線API文檔")
.description("This is a restful api document of demo")
.version("1.0")
.build();
}
}
以上就已經完成了Swagger的配置,是不是很簡潔輕松。
添加一個控制器,在工程下新建 controller包并添加一個 HelloController控制器HelloController.java。
package com.louis.springboot.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
/* 類注解 */
@Api
@RestController
public class HelloController {
/* 方法注解 */
@ApiOperation(value="desc of method", notes="")
@GetMapping(value="/hello")
public Object hello( @ApiParam(value="desc of param" , required=true ) @RequestParam String name) {
return "Hello " + name + "!";
}
}
啟動工程, 打開瀏覽器,訪問:http://localhost:8080/swagger-ui.html,進入swagger接口文檔界面。
完畢收工,這樣管理API接口很方便,并且是和代碼實時更新的,不用煩心再去寫接口文檔啦。
API | 使用位置 |
@Api | 用于controller類上,表示標識這個類是swagger的資源 |
@ApiOperation | 用在controller的方法上,表示一個http請求的操作 |
@ApiParam | 方法中的參數注釋 |
@ApiResponses | 用在controller的方法上 |
@ApiResponse | 用在 @ApiResponses里邊 |
@ApiImplicitParams | 用在controller的方法上 |
@ApiImplicitParam | 用在@ApiImplicitParams的方法里邊 |
@ApiModel | 用在返回對象類上 |
WEB項目開發中碰到的問題千奇百怪。
者:yizhiwazi
鏈接:https://www.jianshu.com/p/7e543f0f0bd8
序言:編寫和維護接口文檔是每個程序員的職責,根據Swagger2可以快速幫助我們編寫最新的API接口文檔,再也不用擔心開會前仍忙于整理各種資料了,間接提升了團隊開發的溝通效率。此外,本教程還額外提供了UI漢化教程,去除閱讀官方英文界面的煩惱。(目前Swagger漢化教程是找不到的,因為官方手冊實在寫得太爛。。)
想必很多小伙伴都曾經使用過Swagger,但是打開UI界面之后,卻是下面這樣的畫風,純英文的界面并不太友好,作為國人還是習慣中文界面。
號稱世界最流行的API工具總不該不支持國際化屬性吧,樓主在官方使用手冊找到關于本地化和翻譯的說明:
也就是說,只要添加翻譯器和對于的譯文JS就可以顯示中文界面了。(使用IDEA 雙擊Shift 快速找到swagger-ui.html 入口文件)
重點來了,在src/main/resources目錄下創建META-INF\resources目錄,然后創建一個名稱為"swagger-ui.html" 的HTML文件。如圖:
注意文件名不要起錯,接下來將下面這段內容原封不動的拷貝進去。
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Swagger UI</title> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/> <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/> <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script> <!--國際化操作:選擇中文版 --> <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script> </head> <body class="swagger-section"> <div id='header'> <div class="swagger-ui-wrap"> <a id="logo" href="http://swagger.io"><span class="logo__title">swagger</span></a> <form id='api_selector'> <div class='input'> <select id="select_baseUrl" name="select_baseUrl"></select> </div> <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div> <div id='auth_container'></div> <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div> </form> </div> </div> <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </body> </html>
OK 大功告成 我們訪問 http://localhost:8080/swagger-ui.html 看看顯示效果:
注:關于國際化,直接在Github下載好Swagger-UI的源碼,將swagger-ui.html替換成上文,直接發布到Maven私服倉庫,使用效果更佳。
如果想進一步調整譯文,可以在META-INF\resources\webjars\springfox-swagger-ui\lang 目錄下添加zh-cn.js文件.
然后在譯文(zh-cn.js )根據個人喜好來添加翻譯內容,如下
'use strict'; /* jshint quotmark: double */ window.SwaggerTranslator.learn({ "Warning: Deprecated":"警告:已過時", "Implementation Notes":"實現備注", "Response Class":"響應類", "Status":"狀態", "Parameters":"參數", "Parameter":"參數", "Value":"值", "Description":"描述", "Parameter Type":"參數類型", "Data Type":"數據類型", "Response Messages":"響應消息", "HTTP Status Code":"HTTP狀態碼", "Reason":"原因", "Response Model":"響應模型", "Request URL":"請求URL", "Response Body":"響應體", "Response Code":"響應碼", "Response Headers":"響應頭", "Hide Response":"隱藏響應", "Headers":"頭", "Try it out!":"試一下!", "Show/Hide":"顯示/隱藏", "List Operations":"顯示操作", "Expand Operations":"展開操作", "Raw":"原始", "can't parse JSON. Raw result":"無法解析JSON. 原始結果", "Example Value":"示例", "Click to set as parameter value":"點擊設置參數", "Model Schema":"模型架構", "Model":"模型", "apply":"應用", "Username":"用戶名", "Password":"密碼", "Terms of service":"服務條款", "Created by":"創建者", "See more at":"查看更多:", "Contact the developer":"聯系開發者", "api version":"api版本", "Response Content Type":"響應Content Type", "Parameter content type:":"參數類型:", "fetching resource":"正在獲取資源", "fetching resource list":"正在獲取資源列表", "Explore":"瀏覽", "Show Swagger Petstore Example Apis":"顯示 Swagger Petstore 示例 Apis", "Can't read from server. It may not have the appropriate access-control-origin settings.":"無法從服務器讀取。可能沒有正確設置access-control-origin。", "Please specify the protocol for":"請指定協議:", "Can't read swagger JSON from":"無法讀取swagger JSON于", "Finished Loading Resource Information. Rendering Swagger UI":"已加載資源信息。正在渲染Swagger UI", "Unable to read api":"無法讀取api", "from path":"從路徑", "server returned":"服務器返回" });
===========接下來,正式進入Swagger2的使用教程===========
<!--依賴管理 --> <dependencies> <dependency> <!--添加Web依賴 --> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency><!--添加Swagger依賴 --> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency><!--添加Swagger-UI依賴 --> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency> <dependency> <!--添加熱部署依賴 --> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> </dependency> <dependency><!--添加Test依賴 --> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies>
@Configuration //標記配置類 @EnableSwagger2 //開啟在線接口文檔 public class Swagger2Config { /** * 添加摘要信息(Docket) */ @Bean public Docket controllerApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("標題:某公司_用戶信息管理系統_接口文檔") .description("描述:用于管理集團旗下公司的人員信息,具體包括XXX,XXX模塊...") .contact(new Contact("一只襪子", null, null)) .version("版本號:1.0") .build()) .select() .apis(RequestHandlerSelectors.basePackage("com.hehe.controller")) .paths(PathSelectors.any()) .build(); } }
Swagger2 基本使用:
Swagger2 使用注解來編寫文檔:
Swagger2編寫接口文檔相當簡單,只需要在控制層(Controller)添加注解來描述接口信息即可。例如:
package com.hehe.controller; @Api("用戶信息管理") @RestController @RequestMapping("/user/*") public class UserController { private final static List<User> userList=new ArrayList<>(); { userList.add(new User("1", "admin", "123456")); userList.add(new User("2", "jacks", "111111")); } @ApiOperation("獲取列表") @GetMapping("list") public List userList() { return userList; } @ApiOperation("新增用戶") @PostMapping("save") public boolean save(User user) { return userList.add(user); } @ApiOperation("更新用戶") @ApiImplicitParam(name="user", value="單個用戶信息", dataType="User") @PutMapping("update") public boolean update(User user) { return userList.remove(user) && userList.add(user); } @ApiOperation("批量刪除") @ApiImplicitParam(name="users", value="N個用戶信息", dataType="List<User>") @DeleteMapping("delete") public boolean delete(@RequestBody List<User> users) { return userList.removeAll(users); } } package com.hehe.entity; public class User { private String userId; private String username; private String password; public User() { } public User(String userId, String username, String password) { this.userId=userId; this.username=username; this.password=password; } @Override public boolean equals(Object o) { if (this==o) { return true; } if (o==null || getClass() !=o.getClass()) { return false; } User user=(User) o; return userId !=null ? userId.equals(user.userId) : user.userId==null; } @Override public int hashCode() { int result=userId !=null ? userId.hashCode() : 0; result=31 * result + (username !=null ? username.hashCode() : 0); result=31 * result + (password !=null ? password.hashCode() : 0); return result; } public String getUserId() { return userId; } public void setUserId(String userId) { this.userId=userId; } public String getUsername() { return username; } public void setUsername(String username) { this.username=username; } public String getPassword() { return password; } public void setPassword(String password) { this.password=password; } }
4. 查閱接口文檔
編寫文檔完成之后,啟動當前項目,在瀏覽器打開:
[ http://localhost:8080/swagger-ui.html ] , 看到效果如下:
來看看save 方法的具體描述,可以看到Swagger 2.7.0 版本對參數列表進行了改版,直接輸入參數,更方便進行測試操作:
Swagger2的強大之處不僅在于快速生成整潔優雅的RestAPI文檔,同時支持接口方法的測試操作(類似于客戶端PostMan)。
以查詢用戶列表為例,無參數輸入,直接點擊“試一下”按鈕:
然后可以看到以JSON格式返回的用戶列表信息,很方便有木有:
好了,關于Swagger2在項目中的使用教程就到這里。
*請認真填寫需求信息,我們會在24小時內與您取得聯系。