SpringBoot 實戰 (四) | 整合 Swagger2 構建強大的 RESTful API 文件

一個優秀的廢人發表於2019-02-19
Spring BootSwaggerRESTAPI

微信公眾號：一個優秀的廢人 如有問題或建議，請後臺留言，我會盡力解決你的問題。

前言

快過年了，不知道你們啥時候放年假，忙不忙。反正我是挺閒的，所以有時間寫 blog。今天給你們帶來 SpringBoot 整合 Swagger2 的教程。

什麼是 Swagger2

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。

為什麼使用 Swagger2 ？

相信剛開始不熟悉 web 開發的時候，大家都有手寫 Api 文件的時候。而手寫 Api 文件主要有以下幾個痛點：

  1. 文件需要更新的時候，需要再次傳送一份給前端，也就是文件更新交流不及時。
  2. 介面返回結果不明確。
  3. 不能直接線上測試介面，通常需要使用工具，比如 postman。
  4. 介面文件太多，不好管理。

這些痛點在前後端分離的大型專案上顯得尤為煩躁。而 Swagger2 的出現恰好能個解決這些痛點。因為 Swagger2 有以下功能：

  1. 文件自動更新，只要生成 Api 的網址沒變，基本不需要跟前端溝通。
  2. 介面返回結果非常明確，包括資料型別，狀態碼，錯誤資訊等。
  3. 可以直接線上測試文件，而且還有例項提供給你。
  4. 只需要一次配置便可使用，之後只要會有一份介面文件，非常易於管理。

整合演示

首先新建一個 SpringBoot 專案，還不會的參考我這篇舊文—— 如何使用 IDEA 構建 Spring Boot 工程

構建時，在選擇依賴那一步勾選 Web、LomBok、JPA 和 Mysql 依賴。其中 Mysql 可以不勾，因為我這裡用於操作實際的資料庫，所以我勾選了。

生成 SpringBoot 後的 Pom 檔案依賴如下：這裡使用的是 2.4.0 的 Swagger2 版本。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.nasus</groupId>
    <artifactId>swagger2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger2</name>
    <description>Demo project for Swagger2</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </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.4.0</version>
        </dependency>

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

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>
複製程式碼

第二步，在 SpringBoot 啟動類（Application）的同級目錄新建一個 Swagger 配置類，注意 Swagger2 配置類必須與專案入口類 Application 位於同一級目錄，否則生成 Api 文件失敗，程式碼如下：

package com.nasus;

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;

/**
 * Project Name:swagger2-demo <br/>
 * Package Name:com.nasus <br/>
 * Date:2019/1/22 22:52 <br/>
 * <b>Description:</b> TODO: 描述該類的作用 <br/>
 *
 * @author <a href="turodog@foxmail.com">nasus</a><br/>
 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@Configuration
// 啟用 Swagger2
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 文件資訊物件
                .apiInfo(apiInfo())
                .select()
                // 被註解的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 標題
                .title("springboot 利用 swagger 構建 API 文件")
                // Api 文件描述
                .description("簡單優雅的 restful 風格，https://blog.csdn.net/turodog/")

                .termsOfServiceUrl("https://blog.csdn.net/turodog/")
                // 文件作者資訊
                .contact(new Contact("陳志遠", "https://github.com/turoDog", "turodog@foxmail.com"))
                // 文件版本
                .version("1.0")
                .build();
    }
}
複製程式碼

第三步，配置被註解的 Controller 類，編寫各個介面的請求引數，返回結果，介面描述等等，程式碼如下：

package com.nasus.controller;

import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
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 springfox.documentation.annotations.ApiIgnore;

/**
 * Project Name:swagger2-demo <br/>
 * Package Name:com.nasus.controller <br/>
 * Date:2019/1/22 22:07 <br/>
 * <b>Description:</b> TODO: 描述該類的作用 <br/>
 *
 * @author <a href="turodog@foxmail.com">nasus</a><br/>
 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@RestController
@RequestMapping("/student")
// @Api：修飾整個類，描述Controller的作用
@Api("StudentController Api 介面文件")
public class StudentController {

    @Autowired
    private StudentService studentService;

    // @ApiOperation：描述一個類的一個方法，或者說一個介面
    @ApiOperation(value="獲取所有學生列表", notes="獲取所有學生列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<Student> getStudent() {
        List<Student> list = studentService.findAll();
        return list;
    }

    @ApiOperation(value="新增學生資訊", notes="新增學生資訊")
    // @ApiImplicitParam：一個請求引數
    @ApiImplicitParam(name = "student", value = "學生資訊詳細實體", required = true, dataType = "Student")
    @PostMapping("/save")
    public Student save(@RequestBody Student student){
        return studentService.save(student);
    }

    @ApiOperation(value="獲學生資訊", notes="根據url的id來獲取學生詳細資訊")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
    @GetMapping("/{id}")
    public Student findById(@PathVariable("id") Integer id){
        return studentService.findById(id);
    }

    @ApiOperation(value="刪除學生", notes="根據url的id來指定刪除的學生")
    @ApiImplicitParam(name = "id", value = "學生ID", required = true, dataType = "Integer",paramType = "path")
    @DeleteMapping("/{id}")
    public String deleteById(@PathVariable("id") Integer id){
        studentService.delete(id);
        return "success";
    }

    @ApiOperation(value="更新學生資訊", notes="根據url的id來指定更新學生資訊")
    // @ApiImplicitParams：多個請求引數
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "學生ID", required = true, dataType = "Integer",paramType = "path"),
            @ApiImplicitParam(name = "student", value = "學生實體student", required = true, dataType = "Student")
    })
    @PutMapping(value="/{id}")
    public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
        Student oldStudent = this.findById(id);
        oldStudent.setId(student.getId());
        oldStudent.setName(student.getName());
        oldStudent.setAge(student.getAge());
        studentService.save(oldStudent);
        return "success";
    }

    // 使用該註解忽略這個API
    @ApiIgnore
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}
複製程式碼

第四步，啟動專案，訪問 http://localhost:8080/swagger-ui.html 地址，結果如下圖：

執行結果

專案原始碼

github

圖解介面

引數解釋

引數解釋

測試結果

Swagger2 常用註解簡介

@ApiOperation：用在方法上，說明方法的作用
  1.value: 表示介面名稱
  2.notes: 表示介面詳細描述 
@ApiImplicitParams：用在方法上包含一組引數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
  1.paramType：引數位置
  2.header 對應註解：@RequestHeader
  3.query 對應註解：@RequestParam
  4.path  對應註解: @PathVariable
  5.body 對應註解: @RequestBody
  6.name：引數名
  7.dataType：引數型別
  8.required：引數是否必須傳
  9.value：引數的描述
  10.defaultValue：引數的預設值
@ApiResponses：用於表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
  1.code：狀態碼
  2.message：返回自定義資訊
  3.response：丟擲異常的類
@ApiIgnore: 表示該介面函式不對swagger2開放展示
@Api：修飾整個類，描述Controller的作用
@ApiParam：單個引數描述
@ApiModel：用物件來接收引數
@ApiProperty：用物件接收引數時，描述物件的一個欄位
@ApiIgnore：使用該註解忽略這個API
@ApiError ：發生錯誤返回的資訊
複製程式碼

注意事項

@ApiImplicitParam 註解下的 paramType 屬性,會影響介面的測試,如果設定的屬性跟spring 的註解對應不上,會獲取不到引數,例如 paramType=path ,函式內卻使用@RequestParam 註解,這樣,可能會獲取不到傳遞進來的引數,需要按照上面進行對應,將 @RequestParam 註解改為 @PathVariable 才能獲取到對應的引數。

後語

以上就是我對 Swagger2 的理解與使用，以上只是教大家入門 Swagger2 ，想要深入使用還是希望自行查閱官方文件。最後，對 Python 、Java 感興趣請長按二維碼關注一波，我會努力帶給你們價值，如果覺得本文對你哪怕有一丁點幫助，請幫忙點好看，讓更多人知道。

另外，關注之後在傳送 1024 可領取免費學習資料。資料內容詳情請看這篇舊文：Python、C++、Java、Linux、Go、前端、演算法資料分享

一個優秀的廢人

相關文章