什么是Swagger?
官方說法：Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
目前的個人見解：Swagger類似于Postman接口測試工具，但是其又比Postman強大很多，更加便于前后端交互和API測試,它可以自動生成文檔和測試接口的ui，較適用于RESTful風格當中使用。
Swagger的一些常用注解：
通過注解接口生成文檔，包括接口名，請求方法，參數，返回信息等
@Api:修飾整個類，用于controller類上（注明當前類的信息）
@ApiOperation:描述一個接口，用戶controller方法上（注明方法信息）
@ApiParam:單個參數描述
@ApiModel:用來對象接收參數,即返回對象
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam:一個請求參數
@ApiImplicitParams:多個請求參數
SpringBoot2.1.1 整合Swagger2:
這里作者使用的是Boot目前的最新版本對Swagger（2.7.0）進行一個簡單的整合及漢化，當然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、服務URL
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 標題
.title("標題：某公司——XXXX——接口文檔")
//模板描述
.description("描述：XXXXXXX，具體包括XXX,XXX模板")
.contact(new Contact("作者XX", url, host)) //當然也可以用null來表示
.version("1.0") //對應的版本號
.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：用在請求的方法上，表示一組參數說明
* @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面 name：參數名
* value：參數的漢字說明、解釋
* required：參數是否必須傳
* paramType：參數放在哪個地方
* · header --> 請求參數的獲取：@RequestHeader
* · query --> 請求參數的獲取：@RequestParam
* · path（用于restful接口）--> 請求參數的獲取：@PathVariable
* · body（不常用）
* · form（不常用）
* dataType：參數類型，默認String，其它值dataType="Integer"
* defaultValue：參數的默認值
* @ApiResponses：用在請求的方法上，表示一組響應
* @ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息 code：數字，例如400
* message：信息，例如"請求參數沒填好"
* response：拋出異常的類
* @ApiModel：用于響應類上，表示一個返回響應數據的信息 （這種一般用在post創建的時候，使用@RequestBody這樣的場景，
* 請求參數無法使用@ApiImplicitParam注解進行描述的時候）
* @ApiModelProperty：用在屬性上，描述響應類的屬性
*/
@Api(tags = "Swagger測試")
@Controller
@Slf4j
public class Mycontroller {
@ApiOperation(value = "查詢學生信息接口", notes = "查詢學生信息")
@GetMapping("/select")
@ResponseBody
public String selectStudentMsg() {
System.out.println("查詢了學生信息");
return "查詢學生信息成功";
}
}
4.結果如下:
Swagger接口測試的地址為（8081為你所設置的端口號，以下的頁面是有經過漢化的，下面也會詳細說下漢化過程）：http://localhost:8081/swagger-ui.html
5.Swagger如何漢化：
首先我們在Maven中所加入的SwaggerUI包中不難看到結果如下：
在倒數第二個我們可以看到swagger-ui.html的html頁面，其實這個頁面也就是Swagger的測試接口顯示頁面，那么如何去漢化呢？
1.首先我們應該找到我們所添加版本的swagger-ui.html然后在項目的resources文件下創建META-INF.resources文件；
2.其次復制jar包中的swagger-ui.html到resources下所創建的META-INF.resources文件中；
3.再者在META-INF.resources文件下創建webjars.springfox-swagger-ui.lang(我們也可以去查看jar包中的lang文件，從中不難看出里面是在存放JS文件的，這么寫的話也就是為了去替換文本做到進行漢化)；
4.最后我們在文件webjars.springfox-swagger-ui.lang中創建我們所定義的js文件（zh-cn.js），并且在html文件中引入我們所創建的js：
/**
* Created by dell on 2018/12/4.
*/
/* 用戶自定義Swagger漢化,可根據自己的需求去做進一步修改*/
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":"服務器返回"
});
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>
