說到swagger，你第一反應想到的是什么呢？是不是這首洗腦神曲，

我們說的swagger當時不是這個洗腦神曲了，

swagger是一款API框架，用于開發中介面測驗使用的，提供了豐富的注解，方便我們在開發中生成api介面檔案以及做介面測驗，學會了swagger，再也不需要postman等介面測驗工具 了，

簡介

官網：https://swagger.io/

• 借助Swagger開源和專業工具集，為用戶，團隊和企業簡化API開發，使用Swagger可以幫助您大規模設計和記錄API，

• 只要匯入專案中，就可以在線訪問，

• 可以在線生成Resutful Api檔案，

SpringBoot集成Swagger

添加依賴

繼承swagger，只需要匯入兩個依賴作標即可（在此之前，需要先創建一個springboot專案，以及匯入web相關依賴，以便之后進行測驗使用，）

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

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

下面是博主測驗使用時的依賴包

因為用到了Lombok，所以IDE得裝上Lombok插件才能用，否則可以選擇移除

<properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>

運行專案

當你匯入好依賴作標后，就已經開始可以使用了，swagger進行了一些默認配置，

訪問/swagger-ui.html這個地址即可，

例如是在本地的8080埠運行的話，就訪問localhost:8080/swagger-ui.html

出現這么個界面就可以正常使用了，

• A：關于介面文旦的說明介紹
• B：分組資訊
• C：專案中需要測驗的api介面
• D：模型類

接下來說說改如何修改配置上面提到的4個資訊

Swagger配置

swagger配置需要用Docket實體，

1、創建一個SwaggerConfig.java，加上@EnableSwagger2表示開啟swagger

package cn.jxj4869.swaggerstart.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

2、創建Docket實體

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }

建構式需要傳入DocumentationType，通過原始碼可以看到DocumentationType給我們提供了三個常量，而我們使用的是swagger2，所以就選擇SWAGGER_2，

public class DocumentationType extends SimplePluginMetadata {
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
    private final MediaType mediaType;

3、通過ApiInfo修改Document也就是A部分（上面那個圖）的資訊，

    @Bean
    public Docket docket() {
        Contact contact = new Contact("jiangxiaoju", "https://blog.csdn.net/qq_43058685", "郵箱");
        ApiInfo apiInfo = new ApiInfo(
                "Swagger配置", // 標題
                "Swagger演示資訊", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/qq_43058685", // 組織鏈接
                contact, // 聯系人資訊
                "Apach 2.0 許可", // 許可
                "許可鏈接", // 許可連接
                new ArrayList<>()// 擴展
        );

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo);
    }

配置好后重啟專案，

4、通過Docket中的select()配置swagger掃描介面的范圍，

默認是掃描整個專案中的api介面，所以在C部分才會顯示一個basic-error-controller介面，如果我們只需要我們自己專案下的api介面資訊，可以通過下面這個配置來實作

    @Bean
    public Docket docket() {
        Contact contact = new Contact("聯系人名字", "http://xxx.xxx.com/聯系人訪問鏈接", "聯系人郵箱");
        ApiInfo apiInfo = new ApiInfo(
                "Swagger學習", // 標題
                "學習演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/組織鏈接", // 組織鏈接
                contact, // 聯系人資訊
                "Apach 2.0 許可", // 許可
                "許可鏈接", // 許可連接
                new ArrayList<>()// 擴展
        );
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .build()
                ;
    }

RequestHandlerSelectors 可以配置掃描的方式，主要有以下幾種

• any：就是掃描所有的介面
• none：所有介面都不掃描
• basePackage：需要傳入一個包名，會掃描該包名下所有的介面

除此之外還可以用path對掃描路徑進行過濾

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .paths(PathSelectors.ant("/jxj4869/**"))  // 掃描以jxj4869開頭的介面 
                .build()
                ;
    }

5、配置swagger的開關

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
            // 選擇是否開啟swagger ，true為開啟，false為關閉
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .paths(PathSelectors.ant("/jxj4869/**"))  // 掃描以jxj4869開頭的介面
                .build()
                ;
    }

6、配置分組資訊

當一個專案需要多個人開發時，每個人負責各自實作的介面，這時候就需要他們可以各自寫api介面檔案，

通過Docket的groupName()方法設定組名

    @Bean
    public Docket docket() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .groupName("組1")
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .paths(PathSelectors.ant("/jxj4869/**"))  // 掃描以jxj4869開頭的介面
                .build()
                ;
    }

如果有多個組的話，可以實體化多個Docket放到容器中就行，

常用注解

下面為swagger中常用的注解，具體用法參考后面的說明

這里說下@ApiParam和@ApiImplicitParam使用時的區別，

• 用@ApiParam備注的引數，引數型別是application/json，適合用在Post等請求型別上，
• 用@ApiImplicitParam備注的引數，引數型別時query，

所以要在get型別的請求介面上，不要使用@ApiParam

模型注解使用

先定義個user類，

• @Data：Lombok中的注解，用于生成getter和setter
• @Accessors：Lombok中的注解，可以使用鏈式呼叫

決議來兩個注解就是swagger中的

• @ApiModel：用來給模型添加描述，
• @ApiModelProperty：作用在模型屬性上，常用的就是備注屬性資訊，還有可以其他的可選引數，可以參考原始碼進行使用，例如顯示變數的型別，是否顯示該備注等，

package cn.jxj4869.swaggerstart.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;

import java.util.Date;


@ApiModel("用戶類")
@Data
@Accessors(chain = true)
public class User {

    @ApiModelProperty("用戶名")
    private String username;

    @ApiModelProperty("密碼")
    private String password;


    @ApiModelProperty("日期")
    private Date date;
}

配置好重啟專案后，就可以看到

Api介面的呼叫

在使用api介面之前，先在controller上，加上一些注解，

package cn.jxj4869.swaggerstart.controller;

import cn.jxj4869.swaggerstart.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@RestController
@Api("這是一個Hello Controller")
public class HelloController {


    @GetMapping("/hello")
    @ApiOperation("這會回傳一個User資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用戶名"),
            @ApiImplicitParam(name = "password",value = "密碼"),}
    )
    public User test(String username, String password) {

        return new User().setPassword(password).setUsername(username).setDate(new Date());
    }

}

配置好后，效果如圖所示

如果一個方法明確了是使用什么型別的請求，例如上面的代碼用了@GetMapping，只能用get請求，所以下面就只顯示了一個api介面

但是如果使用了@RequestMapping，但是沒有明確指明用哪種型別的請求，會把所有的請求型別介面都列出來

接下來測驗使用介面

點擊右上角的 try it out后，輸入對應的引數，點execute就行可以執行力

上面使用了Get方式的請求，接下來我們來試下Post請求方式

   @PostMapping("/hello")
    @ApiOperation("這會回傳一個User資訊")
    public User test1(@ApiParam("用戶名") String username,@ApiParam("密碼") String password) {

        return new User().setPassword(password).setUsername(username).setDate(new Date());
    }

到此Swagger常用方法也都介紹完了，別忘了留下一鍵三連再走，