目錄

一、Swagger簡介

1.1 Swagger是什么？

1.2 為什么要用Swagger

1.3 Swagger注解

二、Spring集成Swagger

三、測試環(huán)境配置

---

一、Swagger簡介

1.1 Swagger是什么？

????????Swagger 是一個開源的 API 設計和文檔工具，它可以幫助開發(fā)人員更快、更簡單地設計、構建、文檔化和測試 RESTful API 。 Swagger 可以自動生成交互式 API 文檔、客戶端 SDK、服務器 stub 代碼等，從而使開發(fā)人員更加容易地開發(fā)、測試和部署 API。

1.2 為什么要用Swagger

1.2.1:對于后端開發(fā)人員來說

• 不用再手寫WiKi接口拼大量的參數(shù)，避免手寫錯誤
• 對代碼侵入性低，采用全注解的方式，開發(fā)簡單
• 方法參數(shù)名修改、增加、減少參數(shù)都可以直接生效，不用手動維護
• 缺點：增加了開發(fā)成本，寫接口還得再寫一套參數(shù)配置

1.2.2:對于前端開發(fā)來說

• 后端只需要定義好接口，會自動生成文檔，接口功能、參數(shù)一目了然
• 聯(lián)調方便，如果出問題，直接測試接口，實時檢查參數(shù)和返回值,就可以快速定位是前端還是后端的問題

1.2.3：對于測試

• 對于某些沒有前端界面UI的功能，可以用它來測試接口
• 操作簡單，不用了解具體代碼就可以操作
• 操作簡單，不用了解具體代碼就可以操作

1.3 Swagger注解

@Api注解?用在類上，說明該類的作用?？梢詷擞浺粋€Controller類做為swagger文檔資源。

屬性	說明
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
produces	返回的格式類型例如："application/json, application/xml"
consumes	接收請求參數(shù)的類型例如："application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置

@ApiOperation注解?用在方法上，說明方法的作用，每一個url資源的定義。

屬性	說明
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
produces	返回的格式類型例如："application/json, application/xml"
consumes	接收請求參數(shù)的類型例如："application/json, application/xml"
hidden	是否在文檔中顯示
notes	注釋說明
response	返回的對象
responseContainer	這些對象是有效的 "List", "Set" or "Map".，其他無效
responseReference	指定對響應類型的引用。指定的引用可以是本地的，也可以是遠程的*將按原樣使用，并覆蓋任何指定的response()類
responseHeaders	響應旁邊提供的可能標題列表
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的狀態(tài)碼 默認 200

@ApilmplicitParam 注解用來描述一個參數(shù)，可以配置參數(shù)的中文含義，也可以給參數(shù)設置默認值，這樣在接口測試的時候可以避免手動輸入；

屬性	說明
paramType	參數(shù)放在哪個地方
name	參數(shù)名稱
value	參數(shù)代表的含義
dataType	參數(shù)類型
dataTypeClass	參數(shù)類型
required	是否必要
defaultValue	參數(shù)的默認值

paramType參數(shù)：

類型	作用
path	以地址的形式提交數(shù)據(jù)，用于restful接口。請求參數(shù)采用@PathVariable獲取
query	直接跟參數(shù)完成自動映射賦值。請求參數(shù)可采用@RequestParam獲取
body	以流的形式提交，僅支持POST。請求參數(shù)采用@RequestBody獲取
header	參數(shù)在request headers里邊提交。請求參數(shù)采用@RequestHeader獲取
form	以form表單的形式提交，僅支持POST。

@ApiModel注解：描述一個Model的信息（這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景，請求參數(shù)無法使用 ?@ApiImplicitParam注解進行描述的時候；

@ApiModelProperty注解描述一個model的屬性。

屬性	說明
value	字段說明
name	參數(shù)名稱
dataType	參數(shù)類型
hidden	在文檔中隱藏
required	是否必要
example	舉例說明
notes	注釋說明

@ApiParam注解?作用在方法的參數(shù)上，用來描述接口的參數(shù)信息(一個參設置一個)

@ApiParam`必須與`@RequestParam`、`@PathVariable`和`@RequestHeader`一起使用。

屬性	說明
name	參數(shù)名稱
value	參數(shù)簡單描述
defaultValue	描述參數(shù)默認值
required	是否為必傳參數(shù), false:非必傳; true:必傳
allowMultiple	指定參數(shù)是否可以通過多次出現(xiàn)來接收多個值
hidden	隱藏參數(shù)列表中的參數(shù)
example	非請求體(body)類型的單個參數(shù)示例
examples	@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 參數(shù)示例，僅適用于請求體類型的請求

二、Spring集成Swagger

1、導入依賴

        <!--swager2--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!--swagger2模版樣式--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version></dependency>

新版（3.0）的直接加入啟動器

        <dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency>

?3.0版本后不需要在加入@enableopenapi，和@enableswagger2這兩個注解

2、創(chuàng)建Swagger2配置類

package com.ycxw.boot.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
@Profile({"dev", "test"})  //dev(開發(fā))、test(測試)、prod(生產(chǎn))
public class Swagger2Configuration extends WebMvcConfigurationSupport {/*** 創(chuàng)建該API的基本信息  http://項目實際地址/doc.html*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("SpringBoot集成Swagger2").description("測試系統(tǒng)").termsOfServiceUrl("ycxw320.blog.csdn.net").version("1.0.0").build();}/*** 創(chuàng)建API應用* apis接口包掃描路徑* apiInfo() 增加API相關信息* 通過select()函數(shù)返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現(xiàn)，* 本例采用指定掃描的包路徑來定義指定要建立API的目錄。*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.ycxw.boot.controller")).paths(PathSelectors.any()).build();}@Overrideprotected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

3、接著通過mybatis生成代碼...

4、Swagger類與屬性注釋

package com.ycxw.boot.entity;import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;import java.io.Serializable;/*** <p>* 書本信息表* </p>** @author 云村小威* @since 2023-12-20*/
@Data
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("書籍對象")
public class Book implements Serializable {private static final long serialVersionUID = 1L;/*** 書本編號*/@TableId("id")@ApiModelProperty("書籍編號")private String id;/*** 書本名稱*/@TableField("bookname")@ApiModelProperty("書籍名稱")private String bookname;/*** 書本價格*/@TableField("price")@ApiModelProperty("書籍價格")private Float price;/*** 書本類型*/@TableField("booktype")@ApiModelProperty("書籍類型")private String booktype;/*邏輯刪除（隱藏）*/@TableField("status")@ApiModelProperty(hidden = true)private Integer status;/*樂觀鎖（隱藏）*/@TableField("version")@ApiModelProperty(hidden = true)private Integer version;}

5、Controller與接口方法注釋

package com.ycxw.boot.controller;import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.toolkit.StringUtils;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.ycxw.boot.entity.Book;
import com.ycxw.boot.service.IBookService;
import com.ycxw.boot.tools.JsonResponseBody;
import com.ycxw.boot.tools.JsonResponseStatus;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.List;
import java.util.Objects;/*** <p>* 書本信息表 前端控制器* </p>** @author 云村小威* @since 2023-12-20*/
@RestController
@RequestMapping("/book")
@Api(value = "書籍管理")
public class BookController {@Autowiredprivate IBookService bookService;@GetMapping("/list")@ApiOperation(value = "書籍查詢所有")public JsonResponseBody<List<Book>> list() {List<Book> list = bookService.list();if (!list.isEmpty()) {return JsonResponseBody.other(JsonResponseStatus.OK);} else {return JsonResponseBody.other(JsonResponseStatus.RESULT_EMPTY);}}@PostMapping("/save")@ApiOperation(value = "新增書籍")public JsonResponseBody<Boolean> save(Book book) {boolean save = bookService.save(book);return JsonResponseBody.success(save);}@GetMapping("/likeName")@ApiOperation(value = "獲取商品集合,模糊查詢")public JsonResponseBody<List<Book>> list(Book goods) {QueryWrapper<Book> wrapper = new QueryWrapper<>();wrapper.like(StringUtils.isNotEmpty(goods.getBookname()), "bookname", goods.getBookname());List<Book> list = bookService.list(wrapper);return JsonResponseBody.success(list);}@GetMapping("/show")@ApiOperation(value = "獲取商品集合,模糊查詢+大于查詢")@ApiImplicitParams({@ApiImplicitParam(name = "price", paramType = "query", value = "價格", required = true),@ApiImplicitParam(name = "bookname", paramType = "query", value = "名稱", required = true)})public JsonResponseBody<List<Book>> listByNameAndPrice(Double price, String bookname) {QueryWrapper<Book> wrapper = new QueryWrapper<>();wrapper.like(StringUtils.isNotEmpty(bookname), "bookname", bookname);wrapper.gt(Objects.nonNull(price), "price", price);List<Book> list = bookService.list(wrapper);return JsonResponseBody.success(list);}@GetMapping("/page")@ApiOperation(value = "獲取商品集合,分頁查詢+模糊查詢")public JsonResponseBody<List<Book>> listPage(@ApiParam(name = "bookname", value = "模糊查詢關鍵字")@RequestParam("bookname")String bookname) {QueryWrapper<Book> wrapper = new QueryWrapper<>();wrapper.like(StringUtils.isNotEmpty(bookname), "bookname", bookname);Page<Book> page = new Page<>();Page<Book> res = bookService.page(page, wrapper);return JsonResponseBody.success(res.getRecords(), res.getTotal());}}

6、訪問本地鏈接

啟動項目訪問：http://localhost:8080/doc.html

????????通過Swagger視圖可以看到該項目的一些信息，還有每個controller層的接口方法，點擊接口可以查看該接口的一些信息，包括請求方式、地址、響應參數(shù)以及結果...

三、測試環(huán)境配置

在swagger配置類中我添加了一個這樣的注解：

@Profile({"dev", "test"})  //dev(開發(fā))、test(測試)、prod(生產(chǎn))

?因為需要配置該測試文檔只能在項目開發(fā)和測試階段才能使用，在yml配置中是這樣配置的：

spring:profiles:active: test

當然這樣定死顯然是不好的，所以去掉這個配置，將項目直接打成jar包，通過指令設置測試環(huán)境運行。

1、設置開發(fā)環(huán)境中打開swagger測試文檔

2、設置生成環(huán)境打開文檔

可以看到在生成環(huán)境中不可查看接口文檔?

????????處于安全考慮，我們在發(fā)布的時候需要關閉Swagger，或者利用security授權登錄才可查看接口文檔

????????作為開發(fā)者，養(yǎng)成良好的文檔規(guī)范習慣是非常重要的，無論使用Swagger還是其他文檔工具，編寫清晰、詳盡的API文檔都應該是我們的素養(yǎng)之一。