一：swagger是什麼？

1、是一款讓你更好的書寫API文件的規範且完整框架。
2、提供描述、生產、消費和視覺化RESTful Web Service。
3、是由龐大工具集合支撐的形式化規範。這個集合涵蓋了從終端使用者介面、底層程式碼庫到商業API管理的方方面面。

方法一：使用第三方依賴（最簡單的方法）

1、在pom.xml檔案中新增第三方swagger依賴（）

    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId
 
>
        <version>1.7.0.RELEASE</version>
    </dependency>

2、在Spring Boot專案的啟動類上新增@EnableSwagger2Doc註解，就可以直接使用啦。
3、https://github.com/SpringForAll/spring-boot-starter-swagger這是GitHub上這個swagger依賴實現的專案，裡面有詳細的講解。

方法二：使用官方依賴

1、在pom.xml檔案中新增swagger相關依賴

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

第一個是API獲取的包，第二是官方給出的一個ui介面。這個介面可以自定義，預設是官方的，對於安全問題，以及ui路由設定需要著重思考。

2、swagger的configuration

需要特別注意的是swagger scan base package,這是掃描註解的配置，即你的API介面位置。

@Configuration
@EnableSwagger2
public class Swagger2 {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                    .paths(PathSelectors.any())
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("服務:釋出為daocke映象,許可權管理，使用者管理，頁面管理，日誌 後臺 APIs")
                    .description("服務:釋出為daocke映象,許可權管理，使用者管理，頁面管理，日誌 後臺")
                    .termsOfServiceUrl("http://192.168.103.198:10070/platformgroup/ms-admin")
                    .contact("程式猿DD")
                    .version("1.0")
                    .build();
        }

    }

三、具體使用

1、在API上做一些宣告

//本controller的功能描述
@Api(value = "pet", description = "the pet API")
public interface PetApi {

    //option的value的內容是這個method的描述，notes是詳細描述，response是最終返回的json model。其他可以忽略
    @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = {
        @Authorization(value = "petstore_auth", scopes = {
            @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
            @AuthorizationScope(scope = "read:pets", description = "read your pets")
            })
    }, tags={ "pet", })

    //這裡是顯示你可能返回的http狀態，以及原因。比如404 not found, 303 see other
    @ApiResponses(value = { 
        @ApiResponse(code = 405, message = "Invalid input", response = Void.class) })
    @RequestMapping(value = "/pet",
        produces = { "application/xml", "application/json" }, 
        consumes = { "application/json", "application/xml" },
        method = RequestMethod.POST)
    ResponseEntity<Void> addPet(
    //這裡是針對每個引數的描述
    @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body);

2、設定訪問API doc的路由

在配置檔案中，application.yml中宣告：

springfox.documentation.swagger.v2.path: /api-docs

這個path就是json的訪問request mapping.可以自定義，防止與自身程式碼衝突。

如果專案是一個webservice，通常設定home / 指向這裡：

@Controller
public class HomeController {

    @RequestMapping(value = "/swagger")
    public String index() {
        System.out.println("swagger-ui.html");
        return "redirect:swagger-ui.html";
    }
}

四：swagger的常用API

1、api標記

Api 用在類上，說明該類的作用。可以標記一個Controller類做為swagger 文件資源，使用方式：
@Api(value = "/user", description = "Operations about user")

2、ApiOperation標記

ApiOperation：用在方法上，說明方法的作用，每一個url資源的定義,使用方式：

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

3、ApiParam標記

ApiParam請求屬性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

4、ApiResponse

ApiResponse：響應配置，使用方式：
@ApiResponse(code = 400, message = "Invalid user supplied")

5、ApiResponses

ApiResponses：響應集配置，使用方式：
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

6、ResponseHeader

響應頭設定，使用方法
@ResponseHeader(name="head1",description="response head conf")