目錄

一、Swagger簡(jiǎn)介

1.1 Swagger是什么？

1.2 為什么要用Swagger

1.3 Swagger注解

二、Spring集成Swagger

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

---

一、Swagger簡(jiǎn)介

1.1 Swagger是什么？

????????Swagger 是一個(gè)開(kāi)源的 API 設(shè)計(jì)和文檔工具，它可以幫助開(kāi)發(fā)人員更快、更簡(jiǎn)單地設(shè)計(jì)、構(gòu)建、文檔化和測(cè)試 RESTful API 。 Swagger 可以自動(dòng)生成交互式 API 文檔、客戶(hù)端 SDK、服務(wù)器 stub 代碼等，從而使開(kāi)發(fā)人員更加容易地開(kāi)發(fā)、測(cè)試和部署 API。

1.2 為什么要用Swagger

1.2.1:對(duì)于后端開(kāi)發(fā)人員來(lái)說(shuō)

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

1.2.2:對(duì)于前端開(kāi)發(fā)來(lái)說(shuō)

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

1.2.3：對(duì)于測(cè)試

• 對(duì)于某些沒(méi)有前端界面UI的功能，可以用它來(lái)測(cè)試接口
• 操作簡(jiǎn)單，不用了解具體代碼就可以操作
• 操作簡(jiǎn)單，不用了解具體代碼就可以操作

1.3 Swagger注解

@Api注解?用在類(lèi)上，說(shuō)明該類(lèi)的作用?？梢詷?biāo)記一個(gè)Controller類(lèi)做為swagger文檔資源。

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

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

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

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

屬性	說(shuō)明
paramType	參數(shù)放在哪個(gè)地方
name	參數(shù)名稱(chēng)
value	參數(shù)代表的含義
dataType	參數(shù)類(lèi)型
dataTypeClass	參數(shù)類(lèi)型
required	是否必要
defaultValue	參數(shù)的默認(rèn)值

paramType參數(shù)：

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

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

@ApiModelProperty注解描述一個(gè)model的屬性。

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

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

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

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

二、Spring集成Swagger

1、導(dǎo)入依賴(lài)

        <!--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）的直接加入啟動(dòng)器

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

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

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

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(開(kāi)發(fā))、test(測(cè)試)、prod(生產(chǎn))
public class Swagger2Configuration extends WebMvcConfigurationSupport {/*** 創(chuàng)建該API的基本信息  http://項(xiàng)目實(shí)際地址/doc.html*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("SpringBoot集成Swagger2").description("測(cè)試系統(tǒng)").termsOfServiceUrl("ycxw320.blog.csdn.net").version("1.0.0").build();}/*** 創(chuàng)建API應(yīng)用* apis接口包掃描路徑* apiInfo() 增加API相關(guān)信息* 通過(guò)select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制哪些接口暴露給Swagger來(lái)展現(xiàn)，* 本例采用指定掃描的包路徑來(lái)定義指定要建立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、接著通過(guò)mybatis生成代碼...

4、Swagger類(lèi)與屬性注釋

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>* 書(shū)本信息表* </p>** @author 云村小威* @since 2023-12-20*/
@Data
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("書(shū)籍對(duì)象")
public class Book implements Serializable {private static final long serialVersionUID = 1L;/*** 書(shū)本編號(hào)*/@TableId("id")@ApiModelProperty("書(shū)籍編號(hào)")private String id;/*** 書(shū)本名稱(chēng)*/@TableField("bookname")@ApiModelProperty("書(shū)籍名稱(chēng)")private String bookname;/*** 書(shū)本價(jià)格*/@TableField("price")@ApiModelProperty("書(shū)籍價(jià)格")private Float price;/*** 書(shū)本類(lèi)型*/@TableField("booktype")@ApiModelProperty("書(shū)籍類(lèi)型")private String booktype;/*邏輯刪除（隱藏）*/@TableField("status")@ApiModelProperty(hidden = true)private Integer status;/*樂(lè)觀(guān)鎖（隱藏）*/@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>* 書(shū)本信息表 前端控制器* </p>** @author 云村小威* @since 2023-12-20*/
@RestController
@RequestMapping("/book")
@Api(value = "書(shū)籍管理")
public class BookController {@Autowiredprivate IBookService bookService;@GetMapping("/list")@ApiOperation(value = "書(shū)籍查詢(xún)所有")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 = "新增書(shū)籍")public JsonResponseBody<Boolean> save(Book book) {boolean save = bookService.save(book);return JsonResponseBody.success(save);}@GetMapping("/likeName")@ApiOperation(value = "獲取商品集合,模糊查詢(xún)")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 = "獲取商品集合,模糊查詢(xún)+大于查詢(xún)")@ApiImplicitParams({@ApiImplicitParam(name = "price", paramType = "query", value = "價(jià)格", required = true),@ApiImplicitParam(name = "bookname", paramType = "query", value = "名稱(chēng)", 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 = "獲取商品集合,分頁(yè)查詢(xún)+模糊查詢(xún)")public JsonResponseBody<List<Book>> listPage(@ApiParam(name = "bookname", value = "模糊查詢(xún)關(guān)鍵字")@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、訪(fǎng)問(wèn)本地鏈接

啟動(dòng)項(xiàng)目訪(fǎng)問(wèn)：http://localhost:8080/doc.html

????????通過(guò)Swagger視圖可以看到該項(xiàng)目的一些信息，還有每個(gè)controller層的接口方法，點(diǎn)擊接口可以查看該接口的一些信息，包括請(qǐng)求方式、地址、響應(yīng)參數(shù)以及結(jié)果...

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

在swagger配置類(lèi)中我添加了一個(gè)這樣的注解：

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

?因?yàn)樾枰渲迷摐y(cè)試文檔只能在項(xiàng)目開(kāi)發(fā)和測(cè)試階段才能使用，在yml配置中是這樣配置的：

spring:profiles:active: test

當(dāng)然這樣定死顯然是不好的，所以去掉這個(gè)配置，將項(xiàng)目直接打成jar包，通過(guò)指令設(shè)置測(cè)試環(huán)境運(yùn)行。

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

2、設(shè)置生成環(huán)境打開(kāi)文檔

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

????????處于安全考慮，我們?cè)诎l(fā)布的時(shí)候需要關(guān)閉Swagger，或者利用security授權(quán)登錄才可查看接口文檔

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