降龍十八掌之SpringBoot 使用Swagger2打造在線接口文檔

序言：編寫和維護接口文檔是每一個程序員的職責，根據Swagger2能夠快速幫助咱們編寫最新的API接口文檔，不再用擔憂開會前仍忙於整理各類資料了，間接提高了團隊開發的溝通效率。此外，本教程還額外提供了UI漢化教程，去除閱讀官方英文界面的煩惱。（目前Swagger漢化教程是找不到的，由於官方手冊實在寫得太爛。。）

SpringBoot + Swagger2 UI界面-漢化教程 1.默認的英文界面UI 想必不少小夥伴都曾經使用過Swagger，可是打開UI界面以後，倒是下面這樣的畫風，純英文的界面並不太友好，做爲國人仍是習慣中文界面。

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

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

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

2.定製中文界面 2.1 添加首頁和譯文 重點來了，在src/main/resources目錄下建立META-INF\resources目錄，而後建立一個名稱爲"swagger-ui.html" 的HTML文件。如圖：

注意文件名不要起錯，接下來將下面這段內容原封不動的拷貝進去。

swagger

Explore

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. 引入依賴

org.springframework.boot spring-boot-starter-web io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0 org.springframework.boot spring-boot-devtools org.springframework.boot spring-boot-starter-test test 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 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")

@DeleteMapping("delete")

public boolean delete(@RequestBody List 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格式返回的用戶列表信息，很方便有木有：

喜歡的點點關注，點點贊。 對Java技術，架構技術感興趣的同窗，歡迎加QQ羣668041364?，一塊兒學習，相互討論。

羣內已經有小夥伴將知識體系整理好（源碼，筆記，PPT，學習視頻），歡迎加羣領取。