Spring Boot 教程 (4) - swagger-ui

来源:https://www.cnblogs.com/Butterfly-Tri/archive/2020/05/23/12944575.html
-Advertisement-
Play Games

Spring Boot 教程 swagger ui 1. 什麼是Swagger? Swagger™的目標是為REST APIs 定義一個標準的，與語言無關的介面，使人和電腦在看不到源碼或者看不到文檔或者不能通過網路流量檢測的情況下能發現和理解各種服務的功能。當服務通過Swagger定義，消費者就能 ...


Spring Boot 教程 - swagger-ui

1. 什麼是Swagger?

Swagger™的目標是為REST APIs 定義一個標準的，與語言無關的介面，使人和電腦在看不到源碼或者看不到文檔或者不能通過網路流量檢測的情況下能發現和理解各種服務的功能。當服務通過Swagger定義，消費者就能與遠程的服務互動通過少量的實現邏輯。類似於低級編程介面，Swagger去掉了調用服務時的很多猜測。
瀏覽 Swagger 去瞭解更多關於Swagger 項目的信息，包括附加的支持其他語言的庫。

2. 在項目中集成Swagger

  • 2.1 引入maven依賴

    我自己的項目中使用的是swagger2。

    <!--springboot父工程-->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <dependencies>
        <!--springboot框架web組件-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.2.2.RELEASE</version>
        </dependency>
        <!--swagger-ui組件-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger組件-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--mybatis整合springboot組件-->
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.1.0</version>
        </dependency>
        <!--mysql資料庫連接驅動-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.18</version>
        </dependency>
        <!--lombok組件-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.10</version>
        </dependency>
    </dependencies>

    <build>
        <!--springboot的maven插件-->
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <compilerArgs>
                        <arg>-parameters</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
        </plugins>
    </build>

  • 2.2 Swagger的配置

    SwggerConfig.java：

    package com.butterflytri.config;

import com.google.common.base.Predicates;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

/**
 * @author: WJF
 * @date: 2020/5/21
 * @description: SwaggerConfig
 */

/**
 * {@link Configuration}：標誌這是一個配置類，在spring boot引導類啟動時，會自動載入這個類的配置。
 * {@link Profile}：說明載入配置文件 'application.yml' 時載入對應的配置。
 * {@link EnableSwagger2}：啟用Swagger2的配置。
 */
@Configuration
@Profile("dev")
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket restApi() {
        Class[] classes = this.getClasses();
        Set<String> consumesSet = new HashSet<>();
        consumesSet.add("application/x-www-form-urlencoded");
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .globalOperationParameters(parameters())
            .ignoredParameterTypes(classes)
            .forCodeGeneration(true)
            .consumes(consumesSet)
            .select()
            .apis(Predicates.and(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)))
            .paths(PathSelectors.any())
            .build();
    }

    /**
     * API文檔的基本信息
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("學生管理平臺")
                .description("學生管理平臺文檔")
                .termsOfServiceUrl("http://127.0.0.1:8080/butterflytri/swagger-ui.html")
                .contact(new Contact("wjf", "http://butterflytri.com", "[email protected]"))
                .version("2.0")
                .build();
    }

    /**
     * Swagger2可以在Swagger2文檔中添加參數
     * @return List<Parameter>
     */
    private List<Parameter> parameters() {
        // 添加一個參數butterflytri，參數描述：不死蝶
        ParameterBuilder paramBuilder = new ParameterBuilder();
        List<Parameter> paramList = new ArrayList<Parameter>();
        paramBuilder.name("butterflytri")
                .description("不死蝶")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true)
                .build();
        paramList.add(paramBuilder.build());
        return paramList;
    }


    /**
     * 獲取class數組
     * @return Class[]
     */
    private Class[] getClasses() {
        return new Class[]{};
    }

}

  • 2.3 控制層

    StudentController.java：

    package com.butterflytri.controller;

import com.butterflytri.entity.Student;
import com.butterflytri.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

/**
 * @author: WJF
 * @date: 2020/5/16
 * @description: StudentController
 */
@Api(tags = "學生管理介面")
@RestController
@RequestMapping("/student")
public class StudentController {

    @Resource
    private StudentService studentService;

    /**
     * GET ：請求從伺服器獲取特定資源。舉個例子：GET /student（獲取所有學生）
     * @return List<Student>
     */
    @ApiOperation(value = "查詢所有學生", httpMethod = "GET", notes = "查詢所有學生")
    @GetMapping("/student")
    public List<Student> student() {
        return studentService.findAll();
    }

    /**
     * GET ：請求從伺服器獲取特定資源。舉個例子：GET /student/1（獲取id為1學生）
     * @param id
     * @return Student
     */
    @ApiOperation(value = "查詢學生詳情", httpMethod = "GET", notes = "查詢學生詳情")
    @ApiImplicitParam(name = "id", value = "學生id", required = true, paramType = "form", dataTypeClass = Long.class)
    @GetMapping("/student/{id}")
    public Student student(@PathVariable("id") Long id) {
        return studentService.findOne(id);
    }

    /**
     * POST ：在伺服器上創建一個新的資源。舉個例子：POST /student（添加學生）
     * @param student
     */
    @PostMapping("/student")
    @ApiOperation(value = "添加學生", httpMethod = "POST", notes = "添加學生")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "studentName", value = "學生姓名", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "studentNo", value = "學生學號", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "sex", value = "學生性別", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "age", value = "學生年齡", required = true, paramType = "form", dataTypeClass = Integer.class)
    })
    public void student(@RequestBody Student student) {
        studentService.add(student);
    }

    /**
     * PUT ：更新伺服器上的資源（客戶端提供更新後的整個資源）。舉個例子：PUT /student/1（更新學號為 1 的學生的所有信息）
     * @param id
     */
    @PutMapping("/student/{id}")
    @ApiOperation(value = "根據id修改學生信息(大範圍)", httpMethod = "PUT", notes = "根據id修改學生信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "學生id", required = true, paramType = "from", dataTypeClass = Long.class),
            @ApiImplicitParam(name = "studentName", value = "學生姓名", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "studentNo", value = "學生學號", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "sex", value = "學生性別", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "age", value = "學生年齡", required = true, paramType = "form", dataTypeClass = Integer.class)
    })
    public void updateById(@PathVariable("id") Long id, Student student) {
        studentService.updateAll(id,student);
    }

    /**
     * DELETE ：從伺服器刪除特定的資源。舉個例子：DELETE /student/1（刪除學號為 1 的學生）
     * @param id
     */
    @DeleteMapping("/student/{id}")
    @ApiOperation(value = "根據id刪除學生信息", httpMethod = "DELETE", notes = "根據id刪除學生信息")
    @ApiImplicitParam(name = "id", value = "學生id", required = true, paramType = "from", dataTypeClass = Long.class)
    public void deleteById(@PathVariable("id") Long id) {
        studentService.delete(id);
    }

    /**
     * PATCH ：更新伺服器上的資源（客戶端提供更改的屬性，可以看做作是部分更新），使用的比較少，這裡就不舉例子了。
     * @param id
     * @param student
     */
    @PatchMapping("/student/{id}")
    @ApiOperation(value = "根據id修改學生信息(小範圍)", httpMethod = "PATCH", notes = "根據id修改學生信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "學生id", required = true, paramType = "from", dataTypeClass = Long.class),
            @ApiImplicitParam(name = "studentName", value = "學生姓名", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "studentNo", value = "學生學號", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "sex", value = "學生性別", required = true, paramType = "form", dataTypeClass = String.class),
            @ApiImplicitParam(name = "age", value = "學生年齡", required = true, paramType = "form", dataTypeClass = Integer.class)
    })
    public void updatePart(@PathVariable("id") Long id, Student student) {
        studentService.updatePart(id,student);
    }

}

    這些註解也是很容易理解的，相信各位聰明的技術大牛很快就會使用了。這些註解的具體作用其實看看就懂了，甚至不用去查資料，在這裡解釋下@ApiImplicitParam這個註解的一個屬性paramType，這個屬性的取值有以下幾種：

    • header：放在請求頭，用於請求頭參數的獲取。使用@RequestHeader，在代碼中接收參數。
    • query：用於get請求的參數拼接。使用@RequestParam，在代碼中接收參數。
    • path：用於restful介面請求參數的獲取。使用@PathVariable，在映射地址上接收參數。
    • body：放在請求體中，使用@RequestBody接收參數。
    • form：使用form表單的形式傳遞參數。

  • 2.4 Entity

    Student.java：

    package com.butterflytri.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

import java.io.Serializable;

/**
 * @author: WJF
 * @date: 2020/5/16
 * @description: Student
 */

@ToString
@Getter
@Setter
@ApiModel("學生Entity")
public class Student implements Serializable {

    @ApiModelProperty("學生id")
    private Long id;

    @ApiModelProperty("學生姓名")
    private String studentName;

    @ApiModelProperty("學生學號")
    private String studentNo;

    @ApiModelProperty("性別")
    private String sex;

    @ApiModelProperty("年齡")
    private Integer age;

}

    可以使用@ApiModelProperty註解來標識每個Entity屬性的意思。

  • 2.5 運行結果

    啟動項目，訪問http://127.0.0.1:8080/butterflytri/swagger-ui.html即可看到下麵的頁面：

    點開學生管理介面可以看到StudentController.java中寫的所有介面方法：

    點開下麵的Models，可以看到Entity中的Student.java實體類：

    再點開查詢所有學生這個方法，調用一下這個方法，點擊Try it out測試一下方法：

    在這裡看到了一個參數butterflytri，而且還是必傳參數，這是因為我在SwaggerConfig.java這個配置文件類中進行了配置，不清楚的可以往上翻一翻，看看那個配置類。

    點擊了Try it out按鈕後，隨便給這個參數賦值，反正這個參數沒有什麼，只是給大家做演示看的。然後點擊execute按鈕，就可以看到返回結果：

3. 項目地址

本項目傳送門：spring-boot-swagger-ui

此教程會一直更新下去，覺得博主寫的可以的話，關註一下，也可以更方便下次來學習。


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • Python--集合
    集合（set）是一個無序的不重覆元素序列。 可以使用大括弧 { } 或者 set() 函數創建集合，註意：創建一個空集合必須用 set() 而不是 { }，因為 { } 是用來創建一個空字典。 創建格式：list_1 = {value01,value02,...} 或者 set(value) 集合作 ...
  • Python--文件操作（操作文件）
    文件的操作包含：讀、寫、修改 文件的多種操作： 1 # 讀取文件的所有內容 2 data = open("yesteday.txt", encoding="utf-8") .read() 3 print(data) 4 5 ''' f:文件句柄（包含這個文件的文件名，字元集，大小，在硬碟中的起始位置 ...
  • JAVA設計模式之原型模式（prototype）
    原型模式： 原型模式又叫克隆模式 Java自帶克隆模式 實現克隆模式必須實現Cloneable 介面，如果不實現會發生java.lang.CloneNotSupportedException異常 當某個類的屬性已經設定好需要創建很多相同屬性值的對象的時候使用clone模式非常方便 使用clone模式 ...
  • C++98/11/17表達式類別
    從C++98到C++17，表達式類別與時俱進地改變著。引用綁定、auto、decltype、拷貝省略等功能與表達式類別息息相關。 ...
  • Python 網路編程 netaddr
    1.安裝 netaddr 組件 pip install netaddr -i https://mirrors.aliyun.com/pypi/simple/ from netaddr import IPNetwork print('https://ipjisuanqi.com/#121.224.14 ...
  • 因為一個變數命名的關係中斷了一個while 迴圈
    因為一個變數命名的關係中斷了一個while 迴圈，有點意思，什麼原因？ IDE: Pycharm Community Edition 一、變數命名為 input , 中斷了while 迴圈，不能迴圈提示輸入： def isNum(x): if isinstance(x,int): return Tr ...
  • 數據結構上機實驗（2）
    實操才能去感受自己的缺陷所在，雖然在演算法這一塊很弱勢，但不斷堅持，改變自己。 ...
  • JAVA設計模式之狀態模式（state）
    狀態模式： 根據狀態決定動作 當動作一定但是狀態可擴展適合使用狀態模式 當動作變化不適合 當狀態不會擴展也沒有必要使用使用傳統的switch即可。 先看一個沒有使用狀態模式的例子： package com.srr.dp.state; /** * 我的女朋友有很多種狀態 * 當給我的女朋友添加新的狀態 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類