序言：編寫和維護接口文檔是每個程序員的職責，根據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 UI 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 使用教程

引入依賴

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;

}

}

查閱接口文檔 編寫文檔完成之后，啟動當前項目，在瀏覽器打開：

[ http://localhost:8080/swagger-ui.html ] , 看到效果如下：

來看看save 方法的具體描述，可以看到Swagger 2.7.0 版本對參數列表進行了改版，直接輸入參數，更方便進行測試操作：

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

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

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

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

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

總結

以上是生活随笔為你收集整理的降龙十八掌之SpringBoot 使用Swagger2打造在线接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。

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