SpringBoot + Swagger2 UI界面-漢化教程

1.默認的英文界面UI

想必很多小伙伴都曾經使用過Swagger，但是打開UI界面之后，卻是下面這樣的畫風，純英文的界面並不太友好，作為國人還是習慣中文界面。

號稱世界最流行的API工具總不該不支持國際化屬性吧，樓主在官方使用手冊找到關於本地化和翻譯的說明：

也就是說，只要添加翻譯器和對於的譯文JS就可以顯示中文界面了。（使用IDEA 雙擊Shift 快速找到swagger-ui.html 入口文件）

注：對靜態資源的存放路徑有疑惑的請戳：SpringBoot項目結構說明

2.定制中文界面

2.1 添加首頁和譯文

重點來了，在resoureces目錄下創建\META-INF\resoureces目錄，然后創建一個名稱為"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">![](webjars/springfox-swagger-ui/images/logo_small.png)<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私服倉庫，使用效果更佳。

2.2 更詳細的譯文翻譯（非必需）

如果想進一步調整譯文，可以在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的使用教程===========

SpringBoot + Swagger2 使用教程

1. 引入依賴

    <!--依賴管理 --> <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>

2. 添加配置

@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(); } }

3. 編寫接口文檔

Swagger2 基本使用：

@Api 描述類/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的參數
@ApiImplicitParams 描述方法的參數(Multi-Params)
@ApiIgnore 忽略某類/方法/參數的文檔

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 版本對參數列表進行了改版，直接輸入參數，更方便進行測試操作：

5. 測試接口

Swagger2的強大之處不僅在於快速生成整潔優雅的RestAPI文檔，同時支持接口方法的測試操作（類似於客戶端PostMan）。

以查詢用戶列表為例，無參數輸入，直接點擊“試一下”按鈕：

然后可以看到以JSON格式返回的用戶列表信息，很方便有木有：

好了，關於Swagger2在項目中的使用教程就到這里。

源碼下載： SpringBoot +Swagger2 使用教程

專題閱讀：《SpringBoot 布道系列》

作者：yizhiwazi
鏈接：https://www.jianshu.com/p/7e543f0f0bd8
來源：簡書
簡書著作權歸作者所有，任何形式的轉載都請聯系作者獲得授權並注明出處。

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 SpringBoot集成Swagger2 以及漢化快速教程 springboot項目利用Swagger2生成在線接口文檔接口文檔生成工具Swagger2的使用 springboot使用swagger2生成api文檔 SSH教程從零打造在線網盤系統前言&目錄 Springboot swagger2 導出api文檔 SpringBoot（六） SpringBoot整合Swagger2（自動化生成接口文檔） swagger2 接口文檔,整個微服務接口文檔使用Swagger2構建API文檔依賴接口文檔從Swagger升級成knife4j使用教程（springboot）