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文件。如圖：

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

<!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" >![](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 布道系列》

最后編輯于：2018.08.01 23:27:21

?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發布，文章內容僅代表作者本人觀點，簡書系信息發布平臺，僅提供信息存儲服務。

人面猴
序言：七十年代末，一起剝皮案震驚了整個濱河市，隨后出現的幾起案子，更是在濱河造成了極大的恐慌，老刑警劉巖，帶你破解...
沈念sama閱讀 228,546評論 6贊 533
死咒
序言：濱河連續發生了三起死亡事件，死亡現場離奇詭異，居然都是意外死亡，警方通過查閱死者的電腦和手機，發現死者居然都...
沈念sama閱讀 98,570評論 3贊 418
救了他兩次的神仙讓他今天三更去死
文/潘曉璐我一進店門，熙熙樓的掌柜王于貴愁眉苦臉地迎上來，“玉大人，你說我怎么就攤上這事。” “怎么了？”我有些...
開封第一講書人閱讀 176,505評論 0贊 376
道士緝兇錄：失蹤的賣姜人
文/不壞的土叔我叫張陵，是天一觀的道長。經常有香客問我，道長，這世上最難降的妖魔是什么？我笑而不...
開封第一講書人閱讀 63,017評論 1贊 313
?港島之戀（遺憾婚禮）
正文為了忘掉前任，我火速辦了婚禮，結果婚禮上，老公的妹妹穿的比我還像新娘。我一直安慰自己，他們只是感情好，可當我...
茶點故事閱讀 71,786評論 6贊 410
惡毒庶女頂嫁案：這布局不是一般人想出來的
文/花漫我一把揭開白布。她就那樣靜靜地躺著，像睡著了一般。火紅的嫁衣襯著肌膚如雪。梳的紋絲不亂的頭發上，一...
開封第一講書人閱讀 55,219評論 1贊 324
城市分裂傳說
那天，我揣著相機與錄音，去河邊找鬼。笑死，一個胖子當著我的面吹牛，可吹牛的內容都是我干的。我是一名探鬼主播，決...
沈念sama閱讀 43,287評論 3贊 441
雙鴛鴦連環套：你想象不到人心有多黑
文/蒼蘭香墨我猛地睜開眼，長吁一口氣：“原來是場噩夢啊……” “哼！你這毒婦竟也來了？” 一聲冷哼從身側響起，我...
開封第一講書人閱讀 42,438評論 0贊 288
萬榮殺人案實錄
序言：老撾萬榮一對情侶失蹤，失蹤者是張志新（化名）和其女友劉穎，沒想到半個月后，有當地人在樹林里發現了一具尸體，經...
沈念sama閱讀 48,971評論 1贊 335
?護林員之死
正文獨居荒郊野嶺守林人離奇死亡，尸身上長有42處帶血的膿包…… 初始之章·張勛以下內容為張勛視角年9月15日...
茶點故事閱讀 40,796評論 3贊 354
?白月光啟示錄
正文我和宋清朗相戀三年，在試婚紗的時候發現自己被綠了。大學時的朋友給我發了我未婚夫和他白月光在一起吃飯的照片。...
茶點故事閱讀 42,995評論 1贊 369
活死人
序言：一個原本活蹦亂跳的男人離奇死亡，死狀恐怖，靈堂內的尸體忽然破棺而出，到底是詐尸還是另有隱情，我是刑警寧澤，帶...
沈念sama閱讀 38,540評論 5贊 359
?日本核電站爆炸內幕
正文年R本政府宣布，位于F島的核電站，受9級特大地震影響，放射性物質發生泄漏。R本人自食惡果不足惜，卻給世界環境...
茶點故事閱讀 44,230評論 3贊 347
男人毒藥：我在死后第九天來索命
文/蒙蒙一、第九天我趴在偏房一處隱蔽的房頂上張望。院中可真熱鬧，春花似錦、人聲如沸。這莊子的主人今日做“春日...
開封第一講書人閱讀 34,662評論 0贊 26
一樁弒父案，背后竟有這般陰謀
文/蒼蘭香墨我抬頭看了看天上的太陽。三九已至，卻和暖如春，著一層夾襖步出監牢的瞬間，已是汗流浹背。一陣腳步聲響...
開封第一講書人閱讀 35,918評論 1贊 286
情欲美人皮
我被黑心中介騙來泰國打工，沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留，地道東北人。一個月前我還...
沈念sama閱讀 51,697評論 3贊 392
代替公主和親
正文我出身青樓，卻偏偏與公主長得像，于是被迫代替她去往敵國和親。傳聞我的和親對象是個殘疾皇子，可洞房花燭夜當晚...
茶點故事閱讀 47,991評論 2贊 374

三个男躁一个女,国精产品一区一手机的秘密,麦子交换系列最经典十句话,欧美国产综合欧美视频

SpringBoot 使用Swagger2打造在線接口文檔（附漢化教程）

SpringBoot 使用Swagger2打造在線接口文檔（附漢化教程）

SpringBoot + Swagger2 UI界面-漢化教程

1.默認的英文界面UI

2.定制中文界面

2.1 添加首頁和譯文

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

SpringBoot + Swagger2 使用教程

1. 引入依賴

2. 添加配置

3. 編寫接口文檔

Swagger2 基本使用：

Swagger2 使用注解來編寫文檔：

4. 查閱接口文檔

5. 測試接口

推薦閱讀更多精彩內容

三个男躁一个女,国精产品一区一手机的秘密,麦子交换系列最经典十句话,欧美 国产 综合 欧美 视频

SpringBoot 使用Swagger2打造在線接口文檔（附漢化教程）

SpringBoot + Swagger2 UI界面-漢化教程

1.默認的英文界面UI

2.定制中文界面

2.1 添加首頁和譯文

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

SpringBoot + Swagger2 使用教程

1. 引入依賴

2. 添加配置

3. 編寫接口文檔

Swagger2 基本使用：

Swagger2 使用注解來編寫文檔：

4. 查閱接口文檔

5. 測試接口

推薦閱讀更多精彩內容

三个男躁一个女,国精产品一区一手机的秘密,麦子交换系列最经典十句话,欧美国产综合欧美视频