1、Swagger2是什麼？

Swagger 是一款RESTFUL介面的文件線上自動生成+功能測試功能軟體。

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。官網：http://swagger.io/GitHub地址：https://github.com/swagger-api/swagger-ui

2、Swagger2官網

3.Swagger2的入門教程

在微服務架構流行的今天，RESTful API成了服務間互動的主要方式之一，Swagger則成為服務之間的契約描述、提高除錯、測試效率的重要工具。 Swagger工具包括Swagger Editor、Swagger UI、Swagger Codegen：

• Swagger Editor——支援編輯Swagger API規範yaml文件描述API，並可實時預覽API。
• SwaggerUI——API線上文件生成和測試的工具，可顯示API描述，並且支援呼叫API進行測試及驗證。
• Swagger Codegen——一個模板驅動引擎，通過分析使用者Swagger資源宣告以各種語言生成客戶端SDK或Server端樁程式碼，從而讓開發團隊能夠更好的關注API的實現和呼叫，提高開發效率.

3.1Swagger2的maven依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
 
    <version>2.4.0</version>
</dependency>

3.2SwaggerConfig的配置

/**
 * Created by Zhaky on 2017/3/17.
 * @專案名稱:XXXXX
* @類名:SwaggerConfig
* @類的描述: Restapi SwaggerConfig的基本配置
 * @作者:Zhaky
* @建立時間:2017/3/17
* @公司:xiaomi
* @QQ:411172392
* @郵箱:[email protected]
* @使用方法：Restful API 訪問路徑: http://localhost:{port}/{ProjectName}/swagger-ui.html
 */
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;
@EnableWebMvc
@EnableSwagger2//啟用Swagger2
@Configuration//讓Spring來載入該類配置
@ComponentScan(basePackages ="com.xiaomi.XXXX")
public class SwaggerConfig {

@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaomi.XXXX"))//controller路徑
.paths(PathSelectors.any())
                .build();
}

private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
                .title("開放介面API")
                .termsOfServiceUrl("https://XXXXXXX/openapi/")
                .description("XXXXXX")
                .contact(new Contact("[email protected]", "https://XXXXX.com/", "[email protected]"))
                .version("1.0")
                .build();
}
}

3.3在Controller中新增

/**
 * 
 * Created by Zhaky on 2017/1/23.
 */
@RestController
@RequestMapping("/pay")
@Api(value = "XXXController", description = "查詢相關操作")
public class XXXController {
private final static Logger logger = LoggerFactory.getLogger(XXXController.class);
@Resource
private LogServiceImpl logServiceImpl;
/**
     * 查詢
     */
@ApiOperation(value = "XX查詢", notes = "查詢資訊")
@RequestMapping(value = {"/payQuery"}, method = {RequestMethod.POST})

public
@ResponseBody
void payQuery(@RequestBody @Valid PayQuery requestVO, BindingResult result, HttpServletRequest req, HttpServletResponse resp) {
try {
            ExecutorService pool = Executors.newCachedThreadPool();
pool.execute(new Runnable() {
@Override
public void run() {
                    log(req);
};//省略業務邏輯程式碼
            })}}

對於@RequestBody 標記的表單引數實體必須在實體中新增@ApiModel註解

@ApiModel(description = "查詢請求表單實體")
@XmlType(name="PayQuery")
public class PayQuery extends BaseBody  {

@NotNull(message = "{common.oriReqMsgId.not.empty}")
@Length(min=0, max=32)
@ApiModelProperty(value = "原交易流水號oriReqMsgId", example = "273453459302",position = 1)
private String oriReqMsgId;//原交易流水號
   //省略部分程式碼
   }

遇到的問題

Swagger-ui.html 404問題

再看看Springfox-swagger-ui的原始碼目錄結構如下： 

By default Spring Boot will serve static content from a directory called /static (or /public or /resources or /META-INF/resources) in the classpath or from the root of the ServletContext。

所以springfox-swagger-ui裡swagger-ui.html的目錄是預設目錄結構。 
顯然兩者的靜態資源目錄結構不一致，若專案首頁能顯示則swagger-ui不能顯示，若swagger-ui頁面能顯示則首頁不能顯示。 

解決方案：

springmvc配置檔案中新增

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

3.4結果

3.5註解說明：

@Api：用在類上，說明該類的作用

@ApiOperation：用在方法上，說明方法的作用，標註在具體請求上，value和notes的作用差不多，都是對請求進行說明；tags則是對請求進行分類的，比如你有好幾個controller，分別屬於不同的功能模組，那這裡我們就可以使用tags來區分了，看上去很有條理

@ApiImplicitParams：用在方法上包含一組引數說明

@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面

paramType：引數放在哪個地方

header-->請求引數的獲取：@RequestHeader

query-->請求引數的獲取：@RequestParam

path（用於restful介面）-->請求引數的獲取：@PathVariable

body（不常用）

form（不常用）

name：引數名

dataType：引數型別

required：引數是否必須傳

value：引數的意思

defaultValue：引數的預設值

@ApiResponses：用於表示一組響應

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊

code：數字，例如400

message：資訊，例如"請求引數沒填好"

response：丟擲異常的類

@ApiModel：描述一個Model的資訊（這種一般用在post建立的時候，使用@RequestBody這樣的場景，請求引數無法使用@ApiImplicitParam註解進行描述的時候）表明這是一個被swagger框架管理的model，用於class上

@ApiModelProperty 這裡顧名思義，描述一個model的屬性，就是標註在被標註了@ApiModel的class的屬性上，這裡的value是對欄位的描述，example是取值例子，注意這裡的example很有用，對於前後端開發工程師理解文件起到了關鍵的作用，因為會在api文件頁面上顯示出這些取值來；這個註解還有一些欄位取值，可以自己研究，舉例說一個：position，表明欄位在model中的順序

以上這些就是最常用的幾個註解了。