swagger是一個前後端api統一文件和測試框架，注意，不光是一個api文件，還可以測試怎麼使用呢 這裡慢慢道來，我們一般用的都是maven工程，所以這裡直接上maven依賴：

<!-- maven依賴 -->
>
<swagger.version>1.5.8</swagger.version>
<io.springfox.version>2.5.0</io.springfox.version>
<!-- swagger start -->

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-core</artifactId>
  <version>${swagger.version}</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>${io.springfox.version}</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>${io.springfox.version}</version>
</dependency>
<!-- swagger end -->
 

>

• 這裡我們需要注入SwaggerConfiguration配置，直接上程式碼：

/**
 * Created by max on 8/16/16.
 *
 */
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
    public Docket getApiInfo() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("outer api")
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(outApiInfo());
}
private ApiInfo outApiInfo() {
        return new ApiInfo(
                "mylearn 前後端介面-外部", // title 標題
                "外部介面文件", // description 描述 標題下
                "1.0.0", // version
                "http://mylearn/*", // termsOfService
                new Contact("xieyuebin","","
 
[email protected]"), // contact
                "Apache 2.0", // licence
                "http://www.apache.org/licenses/LICENSE-2.0.html" // licence url
        );
}
@Bean
    public UiConfiguration getUiConfig() {
        return new UiConfiguration(
                null,// url,暫不用
                "none",       // docExpansion          => none | list
                "alpha",      // apiSorter             => alpha
                "schema",     // defaultModelRendering => schema
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS,
                false,        // enableJsonEditor      => true | false
                true);        // showRequestHeaders    => true | false
    }
 

這是對於文件的說明以及ui的一些配置：

• 然後我們還需要把swagger和spring mvc結合起來，首先在web.xml里加入swagger文件的訪問路徑：

default
/swagger-ui.html

• 然後我們在dispatch-servlet.xml里加入對swagger靜態資源jar包的訪問路徑如下：

這裡我們用到了我們前面定義的SwaggerConfiguration類

然後我們在controller和請求引數和返回引數里加入swagger提供的註解，直接上例子
入參：

/**
 * Created by max on 10/11/16.
 */
@ApiModel(description = "使用者請求表單")
public class UserForm {
@ApiModelProperty(value = "姓名", example = "maxTse",position = 1)
    private String username;
public String getUsername() {
        return username;
    }
public void setUsername(String username) {
        this.username = username;
    }
@Override
    public String toString() {
        return "UserForm{" +
                "username='" + username + '\'' +
                '}';
    }
}

返回值：

@JsonInclude(JsonInclude.Include.NON_NULL)
@ApiModel
public class OutResult<T> implements Serializable {
@ApiModelProperty(value = "資料", example = "")
    public T data;
@ApiModelProperty(value = "狀態碼,0表示成功 其他表示失敗", example = "0")
    public int status;
@ApiModelProperty(value = "錯誤資訊", example = "操作成功")
    public String message = "";

controller：

/**
 * Created by max on 8/16/16.
 */
@Controller
@RequestMapping(value = "/test", consumes = "application/json", produces = "application/json")
public class TestController {
private static final Logger LOGGER = LoggerFactory.getLogger(TestController.class);
@ApiOperation(value = "swagger test", notes = "swagger test first", tags = {SwaggerConstants.TEST_TAG})
    @ResponseBody
    @RequestMapping(value = "/first", method = RequestMethod.POST)
    public OutResult<String> first(@RequestBody UserForm userForm) {
        LOGGER.info("first userForm={}", userForm);
        throw new RuntimeException("dd");
/*
        return OutResult.successResult(userForm.getUsername());
*/
    }

這裡挨個註解解釋下：

1. @ApiModel 表明這是一個被swagger框架管理的model，用於class上

2. @ApiModelProperty 這裡顧名思義，就是標註在被標註了

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

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

下面我們啟動專案，然後通過

url：localhost:8080/swagger-ui.html 來訪問。

就可以看到swagger文件介面了這裡是請求和返回結果的介面，看到這個介面是不是對剛才我們貼出來的具體例子裡的註解上的每個值有所瞭解了，一一對應便能瞭解他們的作用我們開始說了，這個不僅可以當文件使，而且還可以進行測試，沒錯，看看引數介面大家都知道了，實際上引數介面就在請求和返回結果的下面：

看到右上方的大紅框，就是我們的入參格式，注意，這裡是json格式的
然後我們可以在具體填入自己的請求引數後，點選下方的try it out按鈕，就可以進行測試了。

>

總結：使用swagger2.0框架大概這麼幾步：

1.新增maven依賴

2.編寫SwaggerConfiguration配置

3.web.xml裡新增swagger文件的訪問路徑，是靜態資源

4.新增相關的spring mvc配置

5.在請求的入參和返回值 以及具體的請求上新增相應的註解

6.啟動專案，訪問swagger.html

注意：

由於這裡使用的是json格式的入參和返回值，那麼我們在controller的請求引數那裡要加上@RequestBody註解，並且請求方法必須是post。

官方文件：