SpringBoot使用Swagger范例講解
更新時間：2022年07月06日 09:54:02 作者：華仔仔coding
Swagger是一個規(guī)范和完整的框架，用于生成、描述、調用和可視化 Restful 風格的 Web 服務?？傮w目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法、參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步
1. Swagger 介紹
在一個項目開發(fā)過程中，當前端開發(fā)人員根據后端開發(fā)人員給出的 API 接口文檔進行接口聯調對接時，可能會出現這樣的矛盾：前端開發(fā)人員抱怨后端開發(fā)人員給出的 API 接口文檔和實際的情況有所出入，而后端開發(fā)人員由于繁重的開發(fā)任務已經身心俱疲，想到自己還要負責維護接口文檔的任務更是不堪重負。
這時就需要一個解決方案，希望它能夠在后端開發(fā)人員進行接口開發(fā)時，能夠幫助后端工程師自動生成相應的接口文檔，當接口有變化時，也能夠對文檔進行及時更新，這樣前端工程師在進行接口聯調時，不會再出現發(fā)現文檔和實際情況不一致的情況。
幸運的是，偉大的開源社區(qū)就給出了這樣的一套解決方案，稱為 Swagger，正如它的中譯一樣，讓后端工程師能夠大搖大擺地走，以后再面對前端工程師時神奇十足哈哈！
Swagger 是一個規(guī)范和完整的框架，它用于生成、描述、調用和可視化 RESTful 風格的 Web 服務，避免手動維護 API 文檔的帶來的麻煩。
后端工程師只需要按照它的規(guī)范去定義接口及接口相關的信息，再通過 Swagger 衍生出來的一系列項目和工具，就可以做到生成各種格式的接口文檔，生成多種語言的客戶端和服務端的代碼，以及在線接口調試頁面等等。
這樣，如果按照新的開發(fā)模式，在開發(fā)新版本或者迭代版本的時候，只需要更新 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 文檔接口。
第一步，創(chuàng)建一個名為 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 目錄下創(chuàng)建 application.yml 文件
server:
port: 9000 #指定服務端口號
第三步，創(chuàng)建實體類 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;
}第四步，創(chuàng)建 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";
}
}第五步，創(chuàng)建 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();
}
}第六步，創(chuàng)建啟動類
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 執(zhí)行，便可以在 Server response 下方看到響應結果
當然，還可以測試其他的接口，觀察響應數據，為了使得篇幅不那么冗長，這里就不再演示了嗎，以上便是在 SpringBoot 項目中使用 Swagger 接口文檔演示的整個過程。
到此這篇關于SpringBoot使用Swagger范例講解的文章就介紹到這了,更多相關SpringBoot Swagger內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
您可能感興趣的文章:
相關文章
Properties是JDK1.0中引入的java類，目前也在項目中大量使用，主要用來讀取外部的配置，那除了這個，你對它其他的一些api也了解嗎？ 你了解它是怎么實現的嗎? 如果不清楚的話，就通過本篇文章帶你一探究竟2022-11-11
關于json序列化(javaBean轉Json的細節(jié)處理)
這篇文章主要介紹了關于json序列化(javaBean轉Json的細節(jié)處理)，具有很好的參考價值，希望對大家有所幫助。2022-03-03
第三方短信發(fā)送平臺有很多種,各個平臺有各自的優(yōu)缺點,在選擇的時候可以根據自己的具體實際情況定奪，本文主要介紹了SpringBoot發(fā)送短信驗證碼的實例，感興趣的可以了解一下2022-02-02
Spring-AOP @AspectJ進階之如何綁定代理對象
這篇文章主要介紹了Spring-AOP @AspectJ進階之如何綁定代理對象的操作，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-07-07
Spring Cloud Gateway旨在為微服務架構提供一種簡單有效的、統一的 API 路由管理方式。Spring Cloud Gateway 作為 Spring Cloud 生態(tài)系中的網關，它不僅提供統一的路由方式，并且基于 Filter 鏈的方式提供了網關基本的功能，例如：安全、監(jiān)控/埋點和限流等2022-10-10
最近在工作中遇到了一個問題，需要極速的部署Spring Boot應用，發(fā)現網上這方面的資料較少，所以自己來總結下，這篇文章主要給大家介紹了關于Spring Boot應用的極速部署腳本的相關資料，需要的朋友可以參考借鑒，下面來一起看看吧。2017-08-08
這篇文章主要介紹了Spring Boot 2.X 快速集成單元測試解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2019-08-08
這篇文章主要介紹了java調用接口返回亂碼問題及解決,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2024-05-05
這篇文章主要介紹了Java獲取文件路徑常用方法解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2020-09-09
Java基礎之toString的序列化 匿名對象 復雜度精解
序列化即為把內存中的對象轉換為字節(jié)寫入文件或通過網絡傳輸到遠端服務器，本章節(jié)將帶你了解Java toString的序列化 匿名對象 復雜度，需要的朋友可以參考下2021-09-09