前后端分離必備工具：SpringBoot集成Swagger超詳細教程-有解無憂

- 1. 新建springboot專案
- 2. 匯入Swagger依賴
- 3. 撰寫HelloController測驗
- 4. 撰寫Swagger配置類
- 5. 測驗進入Sawgger頁面
- 6. 配置Swagger API資訊
- 7. 配置Swagger自定義掃描介面
- 8. 配置是否啟動Swagger
- 9. 配置API檔案分組
- - 1. 設定默認組名
  - 2. 配置多個組
- 10. 配置Model物體類
- - 1. 新建物體類
  - 2. 撰寫對應請求介面
  - 3. 啟動測驗
  - 4. 常用注解
- 11. 測驗Swagger的使用
- - 1. 測驗傳參
  - 2. 測驗錯誤

1. 新建springboot專案

首先新建一個spirngboot專案，勾選組件時勾選Spring-Web

2. 匯入Swagger依賴

springfox-swagger2

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

springfox-swagger-ui

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

3. 撰寫HelloController測驗

我們撰寫一個controller來測驗一下專案是否搭建成功，在主程式同級目錄下新建controller包，其中新建HelloController類

package com.zsr.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello() {
        return "hello";
    }
}

然后啟動主程式，訪問localhost:8080/hello，出現如下結果即成功

4. 撰寫Swagger配置類

在主程式同級目錄下新建config包，其中新建SwaggerConfig配置類

記住用@Configuration注解注明這是配置類
同時用@EnableSwagger2注解開啟Swagger2

package com.zsr.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2//開啟Swagger2
public class SwaggerConfig {

}

5. 測驗進入Sawgger頁面

重啟主程式，訪問localhost:8080/swagger-ui.html

啟動報錯：@EnableSwagger2注解找不到，但是已經匯入了對應的jar包

這時候降級為2.9.2即可使用

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

再次啟動主程式即可成功，然后訪問localhost:8080/swagger-ui.html，即可進入到以下界面

這個界面是Swagger為我們提供的ui界面，我們可以在原始碼中找到它

6. 配置Swagger API資訊

在Swagger提供的ui界面，其中的Swagger資訊模塊我們可以自定義資訊內容

我們只需要在Swagger配置類SwaggerConfig中實體化Docket類隊物件的bean實體，通過配置ApiInfo類的資訊然后傳入Docket的bean實體即可

package com.zsr.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2//開啟Swagger2
public class SwaggerConfig {
    //配置Swagger的Docket的bean實體
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//配置Swagger資訊
    }

    //配置Swagger資訊
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Baret-H",
                "我的Swagger API檔案",
                "1.0",
                "https://bareth.blog.csdn.net/",
                new Contact("Baret-H", "https://bareth.blog.csdn.net/", "1412578784@qq.com"),//作者資訊
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

重啟主程式測驗，可以看到Swagger資訊已經變更成我們定義的資訊

7. 配置Swagger自定義掃描介面

我們在這個ui界面中，可以看到掃描了兩個controller介面；

一個是默認的/error請求，也就是我們啟動springboot主程式未加配置默認訪問8080埠的默認controller
另一個是我們自己寫的/hello請求，對應著HelloController，由于我們用的@RequsetMapping注解，所以請求的方式有以上的六種

接下來我們自己配置以下要掃描的介面

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())//配置Swagger資訊
            .select()
            /**
             * apis():指定掃描的介面
             *  RequestHandlerSelectors:配置要掃描介面的方式
             *       basePackage:指定要掃描的包
             *       any:掃面全部
             *       none:不掃描
             *       withClassAnnotation:掃描類上的注解(引數是類上注解的class物件)
             *       withMethodAnnotation:掃描方法上的注解(引數是方法上的注解的class物件)
             */
            .apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
            /**
             * paths():過濾路徑
             *  PathSelectors:配置過濾的路徑
             *      any:過濾全部路徑
             *      none:不過濾路徑
             *      ant:過濾指定路徑:按照按照Spring的AntPathMatcher提供的match方法進行匹配
             *      regex:過濾指定路徑:按照String的matches方法進行匹配
             */
            .paths(PathSelectors.ant("/zsr/**"))
            .build();
}

其中.select().apis.paths.build是一套組合進行使用

然后我們啟動主程式訪問localhost:8080/swagger-ui.html進行測驗

可以發現No opertations defined in spec，這是因為我們過濾了/zsr下的所有controller

我們將過濾條件更改為過濾全部路徑

.paths(PathSelectors.any)

再次啟動主程式訪問localhost:8080/swagger-ui.html

可以看到只顯示了我們上述自定義的com.zsr.controller下的介面HelloController

.apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))

8. 配置是否啟動Swagger

我么通過Docket物件的.enable方法來配置swagger是否啟動

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())//配置Swagger資訊
            .enable(false)//配置是否啟動swagger,默認為true
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
            .paths(PathSelectors.ant("/zsr/**"))
            .build();
}

更改為false后啟動測驗一下，查看控制臺，無法進入到swagger頁面

如果我們有這樣一個需求：希望Swagger在開發環境中，在正式環境時不能使用

首先要判斷是不是開發環境，可以設定一個flag表示用來表示：flag=1即表示生產環境
然后將flag的值傳給enable(flag)

首先在resources目錄下新建兩種springboot組態檔：

開發環境：application-dev.properties
```
server.port=8081
```
正式環境：application-pro.properties
```
server.port=8082
```

然后在主組態檔application.properties中激活開發環境

spring.profiles.active=dev

然后我們到SwaggerConfig中的docket()方法中添加代碼：

首先給該方法傳一個引數Environment的實體
```
Environment environment
```
首先設定藥配置的Swagger環境：這里可以添加多個環境
```
Profiles profiles = Profiles.of("dev", "test");
```
然后通過environment.acceptsProfiles方法判斷是否處在上一步設定的dev/test環境中，回傳一個boolean的值，我們用flag接收
```
boolean flag = environment.acceptsProfiles(profiles);
```
然后修改enable中的引數為flag，即通過flag來判斷是否開啟Swagger
```
.enable(flag)//通過flag判斷是否開啟
```

完整代碼：

@Configuration
@EnableSwagger2//開啟Swagger2
public class SwaggerConfig {
    //配置Swagger的Docket的bean實體
    @Bean
    public Docket docket(Environment environment) {
        //設定要配置的Swagger環境
        Profiles profiles = Profiles.of("dev", "test");
        //通過environment.acceptsProfiles判斷是否處在自己設定的環境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger資訊
                .enable(flag)//通過flag判斷是否開啟
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
                .paths(PathSelectors.ant("/zsr/**"))
                .build();
    }

    //配置Swagger資訊
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Baret-H",
                "我的Swagger API檔案",
                "1.0",
                "https://bareth.blog.csdn.net/",
                new Contact("Baret-H", "https://bareth.blog.csdn.net/", "1412578784@qq.com"),//作者資訊
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

然后啟動主程式測驗：由于激活了dev開發環境，所以訪問localhost:8081/swagger-ui.html

成功開啟swagger，如果我們修改主組態檔，激活pro正式發布環境

spring.profiles.active=pro

再次重啟主程式測驗，訪問埠8082對應的地址localhost:8082/swagger-ui.html

無法進入，因為pro環境不在我們配置的test/dev環境中，所以無法開啟

9. 配置API檔案分組

1. 設定默認組名

可以看到，我們默認只有一個組且組名為default

我們可以在docket通過.groupName中設定組名

public Docket docket(Environment environment) {
    //設定要配置的Swagger環境
    Profiles profiles = Profiles.of("dev", "test");
    //通過environment.acceptsProfiles判斷是否處在自己設定的環境中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())//配置Swagger資訊
            .groupName("zsr")
            .enable(true)//配置是否啟動swagger,默認為true
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
            .paths(PathSelectors.any())
            .build();
}

重啟測驗，可以看到組名更改為zsr

2. 配置多個組

上述我們成功修改了組名，但是只有一個組，如果我們想要多個組呢？

觀察代碼可以知道，一個Docket實體就對應著一個組，因此我們配置多個docket就對應著多個組

我們新增兩個Docket的bean實體

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("Baret-H");
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("鐘");
}

再次重啟測驗，就可以看到多個組并選擇

10. 配置Model物體類

1. 新建物體類

在主程式同級目錄下新建pojo包，其中新建User物體類

package com.zsr.pojo;

public class User {
    public String username;
    public String password;
}

2. 撰寫對應請求介面

撰寫完物體類，我們在model中還是看不到的，我們還需在HelloController中新增一個方法回傳物體類的實體物件即可映射到物體項中

@GetMapping("/getUser")
public User getUser() {
    return new User();
}

3. 啟動測驗

成功顯示物體類User

4. 常用注解

我們可以在物體類上和其屬性上添加注解來添加對應的注釋

@ApiModel為類添加注釋
@ApiModelProperty為類屬性添加注釋

package com.zsr.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用戶物體")
public class User {
    @ApiModelProperty("用戶名")
    public String username;
    @ApiModelProperty("密碼")
    public String password;
}

重啟測驗，即可以看到注釋資訊

我們同樣可以在Controller類和其中的方法上添加相應的注解

@Api(tags = "Hello控制類")
@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello() {
        return "hello";
    }

    @ApiOperation("hello控制類")
    @GetMapping("/getUser")
    public User getUser() {
        return new User();
    }
}

重啟即可看到對應的注解

11. 測驗Swagger的使用

1. 測驗傳參

我們在HelloController中新增一個方法，引數為username，可以用@ApiParam給該引數添加注解

@GetMapping("/username")
public String getUserName(@ApiParam("用戶名") String username) {
    return username;
}

重啟測驗，可以看到我們添加的注釋

我們可以簡單測驗一下，點擊Try it out；然后以json的格式輸入用戶名，然后點擊Execute執行

可以看到報錯了，這是因為我們是使用的是Get方式：是通過URL的方式傳遞的，而不是通過請求體單獨傳參

我們將代碼修改一下，將GetMapping改為PostMapping

@PostMapping("/username")
public String getUserName(@ApiParam("用戶名") String username) {
    return username;
}

再次以json的格式輸入引數username，可以看到成功了

2. 測驗錯誤

我們在HelloController中新增一個方法，引數為User，可以用@ApiParam給該引數添加注解

然后運行測驗

找到對應的controller，點擊Try it out測驗，輸入用戶名和密碼然后點擊Excute

可以看到我們請求的URL完全正確，但是Response body相應體中用戶名和密碼都為空，這是因為我們的物體類沒有添加對應的GET和SET方法，我們添加上去

package com.zsr.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用戶物體")
public class User {
    @ApiModelProperty("用戶名")
    public String username;
    @ApiModelProperty("密碼")
    public String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

再次啟動測驗，成功！

如果我們修改一下代碼

@PostMapping("/post")
private User postUser(User user) {
    int i = 100 / 0;
    return user;
}

此時測驗肯定會報錯，我們測驗看看，可以看到500錯誤

由此可見，swagger可以讓我們很容易的進行前后端的互動測驗

轉載請註明出處，本文鏈接：https://www.uj5u.com/ruanti/194342.html

標籤：其他

上一篇：「阿里」Java崗168道面試題：jvm+readis+mysql+spring+并發編程

下一篇：Java多執行緒實作TCP網路Socket編程(C/S通信)