一 什麼是swagger

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。

作用：

1. 介面的文件線上自動生成。

2. 功能測試。

Swagger是一組開源專案，其中主要要專案如下：

1. Swagger-tools:提供各種與Swagger進行整合和互動的工具。例如模式檢驗、Swagger 1.2文件轉換成Swagger 2.0文件等功能。

2. Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進行整合。

3. Swagger-js: 用於JavaScript的Swagger實現。

4. Swagger-node-express: Swagger模組，用於node.js的Express web應用框架。

5. Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger相容API動態生成優雅文件。

6. Swagger-codegen：一個模板驅動引擎，通過分析使用者Swagger資源宣告以各種語言生成客戶端程式碼。

二.Springboot整合swagger

1.引入架包 （記得切換匹配的版本），本文采用1.5.2.RELEASE的Springboot版本。

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

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

2.新建swagger類，和啟動類平行目錄，如圖。

Swagger2程式碼如下：

package com.zhang.myblog;

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 Swagger2 {
    //swagger2的配置檔案，這裡可以配置swagger2的一些基本的內容，比如掃描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.zhang.myblog.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //構建 api文件的詳細資訊函式,注意這裡的註解引用的是哪個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("Spring Boot 測試使用 Swagger2 構建RESTful API")
                //建立人
                .contact(new Contact("張大壯", "http://www.github.com/994683607", "[email protected]"))
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }


}

3.測試
輸入網址http://localhost:8080/swagger-ui.html#!/admin-controller/listUsersUsingGET，頁面如下: