Swagger能成為最受歡迎的REST APIs文件生成工具之一，有以下幾個原因：
Swagger 可以生成一個具有互動性的API控制檯，開發者可以用來快速學習和嘗試API。
Swagger 可以生成客戶端SDK程式碼用於各種不同的平臺上的實現。
Swagger 檔案可以在許多不同的平臺上從程式碼註釋中自動生成。
Swagger 有一個強大的社群，裡面有許多強悍的貢獻者。
Swagger 文件提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 NAMES、ORDER 等 API 資訊。

你可以通過一個文字編輯器來編輯 Swagger 檔案，或者你也可以從你的程式碼註釋中自動生成。各種工具都可以使用 Swagger 檔案來生成互動的 API 文件。

一、pom.xml引入基於maven的swagger依賴

<!--swagger依賴-->
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger2</artifactId>
          <version>2.7.0</version>
      </dependency>
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger-ui</artifactId>
          <version>2.7.0</version>
      </dependency>
 

二、編寫SwaggerConfig配置類

SwaggerConfiguration.java

package com.shao.util;


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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置類
 * 通過@Configuration註解，讓Spring來載入該類配置。
 * 再通過@EnableSwagger2註解來啟用Swagger2。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    /**
     * 建立API應用
     * apiInfo() 增加API相關資訊
     * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現，
     * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.shao.controller")) //這裡填寫controller類路徑
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 建立該API的基本資訊（這些基本資訊會展現在文件頁面中）
     * 訪問地址：http://專案實際地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring MVC中使用Swagger2構建RESTful APIs")
                .description("")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("shao")
                .version("1.0")
                .build();
    }
}
 

三、在spring mvc配置xml裡面加入Swagger配置

在spring.xml檔案中配置

<!-- swagger 配置 ,線上版本需要註釋掉 -->
    <bean class="com.shao.util.SwaggerConfiguration"/>

四、controller層的編寫例子

package com.shao.controller;

import com.shao.bean.User;
import com.shao.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

/**
 * Created by shao on 2018/9/18.
 */
@RestController
@Api(tags = "使用者控制層")
@RequestMapping(value = "/user")
public class UserController {

    private Logger logger = LoggerFactory.getLogger(UserController.class);

    @Autowired
    private UserService userService;

    @ApiOperation(value = "儲存使用者資訊")
    @RequestMapping(value = "/saveUser", method = {RequestMethod.POST})
    public Map<String,Object> saveUser(@RequestBody User user){
        boolean res = true;
        try{
            userService.saveUser(user);
        }catch (Exception e){
            logger.info("saveUser方法報錯:"+e.getMessage());
            res = false;
        }
        Map<String,Object> result = new HashMap<>();
        result.put("res",res);
        return result;

    }
}

五、啟動專案