Spring Boot內建Restful Api線上文檔接口調試工具 Swagger

文章目錄

• ​​一、Swagger簡介​​

• ​​Swagger有什麼用？​​

• ​​二、環境準備​​
• ​​三、建構Spring Boot工程​​
• ​​四、引入Swagger依賴​​
• ​​五、編寫一個Test控制器​​
• ​​六、配置Swagger​​
• ​​七、最終測試​​

一、Swagger簡介

Swagger的目标是為REST API 定義一個标準的，與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和了解各種服務的功能。當服務通過Swagger定義，消費者就能與遠端的服務互動通過少量的實作邏輯。類似于低級程式設計接口，Swagger去掉了調用服務時的很多猜測。

Swagger 是一個用于生成、描述和調用 RESTful 接口的 Web 服務。通俗的來講，Swagger 就是将項目中所有（想要暴露的）接口展現在頁面上，并且可以進行接口調用和測試的服務。

Swagger官網位址：​​https://swagger.io/​​

Swagger有什麼用？

• 将項目中所有的接口展現在頁面上，這樣後端程式員就不需要專門為前端使用者編寫專門的接口文檔；
• 當接口更新之後，隻需要修改代碼中的 Swagger 描述就可以實時生成新的接口文檔了，進而規避了接口文檔老舊不能使用的問題；
• 通過 Swagger 頁面，我們可以直接進行接口調用，降低了項目開發階段的調試成本。

二、環境準備

在開始開發之前，我們需要準備一些環境配置:

• jdk 1.8 或其他更高版本
• 開發工具 IDEA
• 管理依賴 Maven

三、建構Spring Boot工程

打開i​

​dea -> file -> Nwe -> Project ,​

​如圖，勾選填寫相關的配置資訊：

勾選一些初始化的依賴配置：

工程搭建完成：

四、引入Swagger依賴

首先，我們要去 mvnrepository 查詢 Swagger 的依賴

将依賴引入工程中：

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

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

五、編寫一個Test控制器

package com.example.swagger_test.controller;

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

/**
 * @author xiaoZhao
 * @date 2022/10/24
 * @describe
 */
@RestController
public class TestController {

    @GetMapping("hello")
    public String hello(){
        return "hello swagger";
    }
}      

六、配置Swagger

編寫Swagger配置類：

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

/**
 * @author xiaoZhao
 * @date 2022/10/24
 * @describe
 */
@Configuration
@EnableSwagger2 // 開啟Swagger2
public class SwaggerConfig {
    // 使用預設配置
}      

通路：​​http://localhost:8080/swagger-ui.html​​ 進入Swagger管理頁面

從上圖可以看到，接口文檔詳細資訊、接口資訊等

配置Swagger資訊：

package com.example.swagger_test.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;

/**
 * @author xiaoZhao
 * @date 2022/10/24
 * @describe
 */
@Configuration
@EnableSwagger2 // 開啟Swagger2
public class SwaggerConfig {

    // 配置Swagger Docket
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置Swagger資訊
    private ApiInfo apiInfo(){
        // 作者資訊
        Contact contact = new Contact("小趙", "https://blog.csdn.net/Zp_insist?type=blog", "[email protected]");

        return new ApiInfo("測試 Swagger API",
                "一個工程用來測試Swagger的使用",
                "1.0",
                "https://blog.csdn.net/Zp_insist?type=blog",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}      

七、最終測試