javascript
降龙十八掌之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 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 使用教程
@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 版本對參數列表進行了改版，直接輸入參數，更方便進行測試操作：
以查詢用戶列表為例，無參數輸入，直接點擊“試一下”按鈕：
然后可以看到以JSON格式返回的用戶列表信息，很方便有木有：
喜歡的點點關注，點點贊。 對Java技術，架構技術感興趣的同學，歡迎加QQ群668041364?，一起學習，相互討論。
群內已經有小伙伴將知識體系整理好（源碼，筆記，PPT，學習視頻），歡迎加群領取。
總結
以上是生活随笔為你收集整理的降龙十八掌之SpringBoot 使用Swagger2打造在线接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： Win10 输入法工具栏抽风，无法调整水
- 下一篇： Flash存储的故事