SpringBoot使用Swagger范例講解

 更新時間:2022年07月06日 09:54:02   作者:華仔仔coding  
Swagger是一個規范和完整的框架,用于生成、描述、調用和可視化 Restful 風格的 Web 服務??傮w目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法、參數和模型緊密集成到服務器端的代碼,允許API來始終保持同步

1. Swagger 介紹

在一個項目開發過程中,當前端開發人員根據后端開發人員給出的 API 接口文檔進行接口聯調對接時,可能會出現這樣的矛盾:前端開發人員抱怨后端開發人員給出的 API 接口文檔和實際的情況有所出入,而后端開發人員由于繁重的開發任務已經身心俱疲,想到自己還要負責維護接口文檔的任務更是不堪重負。

這時就需要一個解決方案,希望它能夠在后端開發人員進行接口開發時,能夠幫助后端工程師自動生成相應的接口文檔,當接口有變化時,也能夠對文檔進行及時更新,這樣前端工程師在進行接口聯調時,不會再出現發現文檔和實際情況不一致的情況。

幸運的是,偉大的開源社區就給出了這樣的一套解決方案,稱為 Swagger,正如它的中譯一樣,讓后端工程師能夠大搖大擺地走,以后再面對前端工程師時神奇十足哈哈!

Swagger 是一個規范和完整的框架,它用于生成、描述、調用和可視化 RESTful 風格的 Web 服務,避免手動維護 API 文檔的帶來的麻煩。

后端工程師只需要按照它的規范去定義接口及接口相關的信息,再通過 Swagger 衍生出來的一系列項目和工具,就可以做到生成各種格式的接口文檔,生成多種語言的客戶端和服務端的代碼,以及在線接口調試頁面等等。

這樣,如果按照新的開發模式,在開發新版本或者迭代版本的時候,只需要更新 Swagger 描述文件,就可以自動生成接口文檔和客戶端服務端代碼,做到調用端代碼、服務端代碼以及接口文檔的一致性。

2. 使用Swagger接口文檔框架

為了簡化 Swagger 的使用,Spring 框架對 Swagger 進行了整合,建立了 Spring-Swagger 項目,之后又更新作 Springfox. 通過在項目中引入 Springfox,可以掃描相關的代碼,生成描述文件以及與代碼一致的接口文檔和客戶端代碼。

引入 Springfox 的 maven 坐標如下

<dependency>
	<!--swagger 文檔的 UI 組件-->
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Swagger 常用的注解及對應的描述如下表所示:

注解描述
@Api用在請求的類上,例如 @Controller,表示對類的說明
@ApiModel用在類上,通常是實體類,表示一個返回響應數據的信息
@ApiModelProperty用在屬性上,描述響應類的屬性
@ApiOperation用在請求的方法上,說明方法的用途、作用
@ApiImplicitParams用在請求的方法上,表示一組參數說明
@ApiImplicitParam用在 @ApiImplicitParams 注解中,指定一個請求參數的各個方面

下面就開始著手在 SpringBoot 項目中使用 Swagger 文檔接口。

第一步,創建一個名為 swagger_demo 的 maven 工程,工程的 pom.xml 文件內容如下

<?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>
    <groupId>com.hzz</groupId>
    <artifactId>swagger_demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
        <relativePath/>
    </parent>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger 文檔的 UI 組件-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>
</project>

第二步,在 resources 目錄下創建 application.yml 文件

server:
  port: 9000    #指定服務端口號

第三步,創建實體類 User 和 Menu

User 類

package com.hzz.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(description = "用戶實體")
public class User {
    @ApiModelProperty(value = "主鍵")
    private int id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年齡")
    private int age;
    @ApiModelProperty(value = "地址")
    private String address;
}

Menu 類

package com.hzz.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(description = "菜單實體")
public class Menu {
    @ApiModelProperty(value = "主鍵")
    private int id;
    @ApiModelProperty(value = "菜單名稱")
    private String name;
}

第四步,創建 UserController 和 MenuController

UserController 類

package com.hzz.controller.user;
import com.hzz.entity.User;
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 java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/user")
@Api(tags = "用戶控制器")
public class UserController {
    @GetMapping("/getUsers")
    @ApiOperation(value = "查詢所有用戶", notes = "查詢所有用戶信息")
    public List<User> getAllUsers() {
        User user = new User();
        user.setId(100);
        user.setName("hzz");
        user.setAge(20);
        user.setAddress("hz");
        List<User> list = new ArrayList<>();
        list.add(user);
        return list;
    }
    @PostMapping("/save")
    @ApiOperation(value = "新增用戶", notes = "新增用戶信息")
    public String save(@RequestBody User user) {
        return "OK";
    }
    @PutMapping("/update")
    @ApiOperation(value = "修改用戶", notes = "修改用戶信息")
    public String update(@RequestBody User user) {
        return "OK";
    }
    @DeleteMapping("/delete")
    @ApiOperation(value = "刪除用戶", notes = "刪除用戶信息")
    public String delete(int id) {
        return "OK";
    }
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "頁碼",
                    required = true, type = "Integer"),
            @ApiImplicitParam(name = "pageSize", value = "每頁條數",
                    required = true, type = "Integer"),
    })
    @ApiOperation(value = "分頁查詢用戶信息")
    @GetMapping(value = "page/{pageNum}/{pageSize}")
    public String findByPage(@PathVariable Integer pageNum,
                             @PathVariable Integer pageSize) {
        return "OK";
    }
}

MenuController 類

package com.hzz.controller.menu;
import com.hzz.entity.Menu;
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 java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/menu")
@Api(tags = "菜單控制器")
public class MenuController {
    @GetMapping("/getMenus")
    @ApiOperation(value = "查詢所有菜單", notes = "查詢所有菜單信息")
    public List<Menu> getMenus() {
        Menu menu = new Menu();
        menu.setId(100);
        menu.setName("hzz");
        List<Menu> list = new ArrayList<>();
        list.add(menu);
        return list;
    }
    @PostMapping("/save")
    @ApiOperation(value = "新增菜單", notes = "新增菜單信息")
    public String save(@RequestBody Menu menu) {
        return "OK";
    }
    @PutMapping("/update")
    @ApiOperation(value = "修改菜單", notes = "修改菜單信息")
    public String update(@RequestBody Menu menu) {
        return "OK";
    }
    @DeleteMapping("/delete")
    @ApiOperation(value = "刪除菜單", notes = "刪除菜單信息")
    public String delete(int id){
        return "OK";
    }
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "頁碼",
                    required = true, type = "Integer"),
            @ApiImplicitParam(name = "pageSize", value = "每頁條數",
                    required = true, type = "Integer"),
    })
    @ApiOperation(value = "分頁查詢菜單信息")
    @GetMapping(value = "page/{pageNum}/{pageSize}")
    public String findByPage(@PathVariable Integer pageNum,
                             @PathVariable Integer pageSize) {
        return "OK";
    }
}

第五步,創建 SwaggerAutoConfiguration 配置類

package com.hzz.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
/**
 * 自動配置類
 */
@Configuration
@EnableSwagger2  //啟動swagger
public class SwaggerAutoConfiguration {
    @Bean
    public Docket createRestApi1() {
        //docket 用于封裝接口文檔相關信息
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .apiInfo(apiInfo()).groupName("用戶接口組")
                .select()
                //為當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.hzz.controller.user"))
                .build();
        return docket;
    }
    @Bean
    public Docket createRestApi2() {
        //docket 用于封裝接口文檔相關信息
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).groupName("菜單接口組")
                .select()
                //為當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.hzz.controller.menu"))
                .build();
        return docket;
    }
    //構建 API 文檔的詳細信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API接口文檔") //頁面標題
                //聯系人
                .contact(new Contact("華仔仔coding", null,null)) //url和email沒有則填充null即可
                .version("1.0")  //版本號
                .description("API 描述")  //描述
                .build();
    }
}

第六步,創建啟動類

package com.hzz;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }
}

第七步,啟動項目,訪問地址 http://localhost:9000/swagger-ui.html,swagger 接口文檔可視化界面如下

此外,還可以在文檔中進行測試,可以點擊某個請求,例如測試上圖中的 DELETE 請求,點擊 Try it out 進行測試接口

然后,輸入請求的參數,點擊 Execute 執行,便可以在 Server response 下方看到響應結果

當然,還可以測試其他的接口,觀察響應數據,為了使得篇幅不那么冗長,這里就不再演示了嗎,以上便是在 SpringBoot 項目中使用 Swagger 接口文檔演示的整個過程。

到此這篇關于SpringBoot使用Swagger范例講解的文章就介紹到這了,更多相關SpringBoot Swagger內容請搜索腳本之家以前的文章或繼續瀏覽下面的相關文章希望大家以后多多支持腳本之家!

相關文章

  • mapper接口注入兩種方式詳解

    mapper接口注入兩種方式詳解

    這篇文章主要介紹了mapper接口注入兩種方式詳解,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下
    2020-02-02
  • java 保留兩位小數的幾種方法

    java 保留兩位小數的幾種方法

    這篇文章主要介紹了JAVA中小數點后保留兩位的幾種方法,并有小實例,希望能幫助有所需要的同學
    2016-07-07
  • springboot配置多數據源后mybatis攔截器失效的解決

    springboot配置多數據源后mybatis攔截器失效的解決

    這篇文章主要介紹了springboot配置多數據源后mybatis攔截器失效的解決方案,具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教
    2021-09-09
  • Spring注解@RestControllerAdvice原理解析

    Spring注解@RestControllerAdvice原理解析

    這篇文章主要介紹了Spring注解@RestControllerAdvice原理解析,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下
    2019-11-11
  • Kotlin 接口與 Java8 新特性接口詳解

    Kotlin 接口與 Java8 新特性接口詳解

    這篇文章主要介紹了Kotlin 接口與 Java8 新特性接口,Kotlin的接口是可以包含屬性聲明。Kotlin默認的聲明是fianl 和public的。 Kotlin里嵌套的類默認并不是內部內,不包含對器外部類的隱式調用。下面我們來一起學習一下吧
    2019-06-06
  • Java實現導出ZIP壓縮包的方法

    Java實現導出ZIP壓縮包的方法

    這篇文章主要介紹了Java實現導出ZIP壓縮包的方法,本文給大家介紹的非常詳細,對大家的學習或工作具有一定的參考借鑒價值,需要的朋友可以參考下
    2020-11-11
  • Java 自定義注解的魅力

    Java 自定義注解的魅力

    這篇文章主要介紹了Java 自定義注解的相關資料,幫助大家更好的理解和學習使用Java,感興趣的朋友可以了解下
    2021-03-03
  • Mybatis如何使用正則模糊匹配多個數據

    Mybatis如何使用正則模糊匹配多個數據

    這篇文章主要介紹了Mybatis如何使用正則模糊匹配多個數據,具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教
    2022-01-01
  • 基于JavaSwing+mysql開發一個學生社團管理系統設計和實現

    基于JavaSwing+mysql開發一個學生社團管理系統設計和實現

    項目使用Java swing+mysql開發,可實現基礎數據維護、用戶登錄注冊、社團信息列表查看、社團信息添加、社團信息修改、社團信息刪除以及退出注銷等功能、界面設計比較簡單易學、適合作為Java課設設計以及學習技術使用,需要的朋友參考下吧
    2021-08-08
  • 關于Spring?Data?Jpa?自定義方法實現問題

    關于Spring?Data?Jpa?自定義方法實現問題

    這篇文章主要介紹了關于Spring?Data?Jpa?自定義方法實現問題,具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教
    2021-12-12

最新評論

美丽人妻被按摩中出中文字幕