點擊進(jìn)入Swagger官網(wǎng)

什么是Swagger?

官方說法：Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件辩涝。Swagger 是一個規(guī)范和完整的框架勘天，用于生成怔揩、描述误辑、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)沧踏〗矶ぃ總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新翘狱。文件的方法砰苍，參數(shù)和模型緊密集成到服務(wù)器端的代碼潦匈，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單茬缩。

目前的個人見解：Swagger類似于Postman接口測試工具赤惊，但是其又比Postman強大很多凰锡，更加便于前后端交互和API測試,它可以自動生成文檔和測試接口的ui未舟，較適用于RESTful風(fēng)格當(dāng)中使用。

Swagger的一些常用注解：

通過注解接口生成文檔掂为，包括接口名裕膀，請求方法，參數(shù)勇哗，返回信息等

@Api:修飾整個類昼扛，用于controller類上（注明當(dāng)前類的信息）

@ApiOperation:描述一個接口，用戶controller方法上（注明方法信息）

@ApiParam:單個參數(shù)描述

@ApiModel:用來對象接收參數(shù),即返回對象

@ApiProperty：用對象接收參數(shù)時欲诺，描述對象的一個字段

@ApiResponse：HTTP響應(yīng)其中1個描述

@ApiResponses：HTTP響應(yīng)整體描述

@ApiError ：發(fā)生錯誤返回的信息

@ApiImplicitParam:一個請求參數(shù)

@ApiImplicitParams:多個請求參數(shù)

SpringBoot2.1.1 整合Swagger2:

這里作者使用的是Boot目前的最新版本對Swagger（2.7.0）進(jìn)行一個簡單的整合及漢化抄谐，當(dāng)然2.0以上版本也是通用的（基本沒什么沖突的哈！扰法！ 若有問題歡迎留言糾正）

1.通過Maven依賴的方式添加Swagger依賴到pom

        <!--Swagger2依賴 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
       <!--Swagger2  UI包 即：可通過html頁面去訪問Swagger測試接口-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

2.書寫Swagger在SpringBoot中的配置類

package com.itcast.swaggertest.config;

/**
 * @authro JIAQI
 * @date 2018/12/4 - 20:51
 */

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定提供接口所在的基包
                .apis(RequestHandlerSelectors.basePackage("com.itcast.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 該套 API 說明蛹含，包含作者、簡介迹恐、版本挣惰、host、服務(wù)URL
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 標(biāo)題
                .title("標(biāo)題：某公司——XXXX——接口文檔")
                //模板描述
                .description("描述：XXXXXXX殴边，具體包括XXX,XXX模板")
                .contact(new Contact("作者XX", url, host))  //當(dāng)然也可以用null來表示
                .version("1.0")  //對應(yīng)的版本號
                .build();
    }
}

3.書寫測試類并運行程序

package com.itcast.swaggertest.controller;

/**
 * @authro JIAQI
 * @date 2018/12/4 - 20:56
 */

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

/**
 * @ApiOperation：用在請求的方法上憎茂，說明方法的用途、作用 value="說明方法的用途竖幔、作用"
 * notes="方法的備注說明"
 * @ApiImplicitParams：用在請求的方法上，表示一組參數(shù)說明
 * @ApiImplicitParam：用在@ApiImplicitParams注解中是偷，指定一個請求參數(shù)的各個方面 name：參數(shù)名
 * value：參數(shù)的漢字說明拳氢、解釋
 * required：參數(shù)是否必須傳
 * paramType：參數(shù)放在哪個地方
 * · header --> 請求參數(shù)的獲取：@RequestHeader
 * · query --> 請求參數(shù)的獲鹊懊：@RequestParam
 * · path（用于restful接口）--> 請求參數(shù)的獲炔銎馈：@PathVariable
 * · body（不常用）
 * · form（不常用）
 * dataType：參數(shù)類型，默認(rèn)String刺啦，其它值dataType="Integer"
 * defaultValue：參數(shù)的默認(rèn)值
 * @ApiResponses：用在請求的方法上留特，表示一組響應(yīng)
 * @ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息 code：數(shù)字，例如400
 * message：信息蜕青，例如"請求參數(shù)沒填好"
 * response：拋出異常的類
 * @ApiModel：用于響應(yīng)類上苟蹈，表示一個返回響應(yīng)數(shù)據(jù)的信息 （這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景右核，
 * 請求參數(shù)無法使用@ApiImplicitParam注解進(jìn)行描述的時候）
 * @ApiModelProperty：用在屬性上慧脱，描述響應(yīng)類的屬性
 */


@Api(tags = "Swagger測試")
@Controller
@Slf4j
public class Mycontroller {
    @ApiOperation(value = "查詢學(xué)生信息接口", notes = "查詢學(xué)生信息")
    @GetMapping("/select")
    @ResponseBody
    public String selectStudentMsg() {
        System.out.println("查詢了學(xué)生信息");
        return "查詢學(xué)生信息成功";
    }
}

4.結(jié)果如下:

Swagger接口測試的地址為（8081為你所設(shè)置的端口號，以下的頁面是有經(jīng)過漢化的贺喝，下面也會詳細(xì)說下漢化過程）：http://localhost:8081/swagger-ui.html

5.Swagger如何漢化：

首先我們在Maven中所加入的SwaggerUI包中不難看到結(jié)果如下：

1.首先我們應(yīng)該找到我們所添加版本的swagger-ui.html然后在項目的resources文件下創(chuàng)建META-INF.resources文件针炉；

2.其次復(fù)制jar包中的swagger-ui.html到resources下所創(chuàng)建的META-INF.resources文件中挠他；

3.再者在META-INF.resources文件下創(chuàng)建webjars.springfox-swagger-ui.lang(我們也可以去查看jar包中的lang文件，從中不難看出里面是在存放JS文件的篡帕，這么寫的話也就是為了去替換文本做到進(jìn)行漢化)殖侵；

4.最后我們在文件webjars.springfox-swagger-ui.lang中創(chuàng)建我們所定義的js文件（zh-cn.js）镰烧，并且在html文件中引入我們所創(chuàng)建的js：

/**
 * Created by dell on 2018/12/4.
 */
/* 用戶自定義Swagger漢化,可根據(jù)自己的需求去做進(jìn)一步修改*/
window.SwaggerTranslator.learn({
    "Warning: Deprecated":"警告：已過時",
    "Implementation Notes":"實現(xiàn)備注",
    "Response Class":"響應(yīng)類",
    "Status":"狀態(tài)",
    "Parameters":"參數(shù)",
    "Parameter":"參數(shù)",
    "Value":"值",
    "Description":"描述",
    "Parameter Type":"參數(shù)類型",
    "Data Type":"數(shù)據(jù)類型",
    "Response Messages":"響應(yīng)消息",
    "HTTP Status Code":"HTTP狀態(tài)碼",
    "Reason":"原因",
    "Response Model":"響應(yīng)模型",
    "Request URL":"請求URL",
    "Response Body":"響應(yīng)體",
    "Response Code":"響應(yīng)碼",
    "Response Headers":"響應(yīng)頭",
    "Hide Response":"隱藏響應(yīng)",
    "Headers":"頭",
    "Try it out!":"試一下拢军！",
    "Show/Hide":"顯示/隱藏",
    "List Operations":"顯示操作",
    "Expand Operations":"展開操作",
    "Raw":"原始",
    "can't parse JSON.  Raw result":"無法解析JSON. 原始結(jié)果",
    "Example Value":"示例",
    "Click to set as parameter value":"點擊設(shè)置參數(shù)",
    "Model Schema":"模型架構(gòu)",
    "Model":"模型",
    "apply":"應(yīng)用",
    "Username":"用戶名",
    "Password":"密碼",
    "Terms of service":"服務(wù)條款",
    "Created by":"創(chuàng)建者",
    "See more at":"查看更多：",
    "Contact the developer":"聯(lián)系開發(fā)者",
    "api version":"api版本",
    "Response Content Type":"響應(yīng)Content Type",
    "Parameter content type:":"參數(shù)類型:",
    "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.":"無法從服務(wù)器讀取≌睿可能沒有正確設(shè)置access-control-origin茉唉。",
    "Please specify the protocol for":"請指定協(xié)議：",
    "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":"服務(wù)器返回"
});

translator.js為國際化的意思结执，此js如果不引用的話是會造成漢化失敗的６嚷健！献幔！

  <!--國際化操作：選擇中文版 -->
    <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>

以上js代碼網(wǎng)上有很多地方可以參考懂傀，大家可根據(jù)自己的需求進(jìn)行進(jìn)一步的修改（懶人的話直接copy使用也問題不大哈，當(dāng)然一定要記得在html文件中引入我們所創(chuàng)建的js文件）蜡感。其實漢化的過程并不復(fù)雜說白了也就是去替換原來jar包的代碼蹬蚁，當(dāng)然不進(jìn)行漢化的話也是無傷大雅的，具體還是看個人喜好郑兴。以上的話只是屬于一個簡單的demo,如果說你是用的是2.8版本的話那么漢化的過程跟2.8以下版本也是有所區(qū)別的。（初寫筆記情连，若有不對的地方還歡迎各位前輩糾正 萬分感謝＿创狻！）