當(dāng)前位置：首頁(yè) > 前端技术 > javascript >内容正文

javascript

Spring Boot——集成Swagger2

發(fā)布時(shí)間：2024/10/5 javascript 29 豆豆

生活随笔收集整理的這篇文章主要介紹了 Spring Boot——集成Swagger2 小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

問(wèn)題描述?

在團(tuán)隊(duì)開(kāi)發(fā)中，一個(gè)好的 API 文檔不但可以減少大量的溝通成本，還可以幫助一位新人快速上手業(yè)務(wù)。傳統(tǒng)的做法是由開(kāi)發(fā)人員創(chuàng)建一份 RESTful API 文檔來(lái)記錄所有的接口細(xì)節(jié)，并在程序員之間代代相傳。

這種做法存在以下幾個(gè)問(wèn)題：

API 接口眾多，細(xì)節(jié)復(fù)雜，需要考慮不同的HTTP請(qǐng)求類型、HTTP頭部信息、HTTP請(qǐng)求內(nèi)容等，想要高質(zhì)量的完成這份文檔需要耗費(fèi)大量的精力；
難以維護(hù)。隨著需求的變更和項(xiàng)目的優(yōu)化、推進(jìn)，接口的細(xì)節(jié)在不斷地演變，接口描述文檔也需要同步修訂，可是文檔和代碼處于兩個(gè)不同的媒介，除非有嚴(yán)格的管理機(jī)制，否則很容易出現(xiàn)文檔、接口不一致的情況
接口測(cè)試不方便，一般只能借助第三方工具（如：Postman）來(lái)測(cè)試。

基本概念?

Swagger2?是一個(gè)開(kāi)源軟件框架，從根本上解決上述問(wèn)題。它作為一個(gè)規(guī)范和完整的框架，可以用于設(shè)計(jì)、生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)，使開(kāi)發(fā)人員將大部分精力集中到業(yè)務(wù)中，而不是繁雜瑣碎的文檔中：

接口文檔在線自動(dòng)生成，文檔隨接口變動(dòng)實(shí)時(shí)更新，節(jié)省維護(hù)成本。
支持在線接口測(cè)試，不依賴第三方工具。
將代碼和文檔融為一體。

Maven

<dependencies>...<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> </dependencies>

解決方案?

配置類?

Swagger2Configuration.java

package com.zstu.metrocity.config;import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @Author ShenTuZhiGang* @Version 1.0.0* @Date 2020-04-13 19:57* Swagger2 配置類*/ @Configuration @EnableSwagger2 public class CustomSwagger2Config {@BeanDocket docket(){return new Docket(DocumentationType.SPRING_WEB).select()//配置需要掃描的controller位置.apis(RequestHandlerSelectors.basePackage("com.zstu.controller"))//配置路徑.paths(PathSelectors.any())//構(gòu)建.build()//文檔信息.apiInfo(new ApiInfoBuilder()//描述.description("MetroCity RESTful API 文檔")//聯(lián)系人信息.contact(new Contact("申屠志剛",//名字"https://shentuzhigang.blog.csdn.net/",//網(wǎng)址"1600337300@qq.com"))//郵箱//版本.version("V1.0")//標(biāo)題.title("MetroCity RESTful API 文檔")//License.license("Apache 2.0")//License 網(wǎng)址.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").build());}}

Swagger2Configuration.java 配置類的內(nèi)容不多，配置完成后也很少變化，簡(jiǎn)單了解即可。

如上代碼所示，通過(guò) @Configuration 注解，讓 Spring 加載該配置類。再通過(guò) @EnableSwagger2 注解來(lái)啟用Swagger2。成員方法 createRestApi 函數(shù)創(chuàng)建 Docket 的Bean之后，apiInfo() 用來(lái)創(chuàng)建該 Api 的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁(yè)面中）。select() 函數(shù)返回一個(gè) ApiSelectorBuilder實(shí)例用來(lái)控制哪些接口暴露給 Swagger 來(lái)展現(xiàn)，本例采用指定掃描的包路徑來(lái)定義，Swagger 會(huì)掃描該包下所有 Controller 定義的 API，并產(chǎn)生文檔內(nèi)容（除了被 @ApiIgnore 指定的請(qǐng)求）。

API 接口編寫

在完成了上述配置后，其實(shí)已經(jīng)可以產(chǎn)生文檔內(nèi)容，但是這樣的文檔主要針對(duì)請(qǐng)求本身，而描述主要來(lái)源于函數(shù)等命名產(chǎn)生，對(duì)用戶并不友好，我們通常需要自己增加一些說(shuō)明來(lái)豐富文檔內(nèi)容。

@Api(description = "生產(chǎn)者進(jìn)程API接口") @RestController @RequestMapping("/producer") public class ActiveMQProducer {private static final Logger logger = LoggerFactory.getLogger(ActiveMQConsumer.class);@Value(value = "${mq.active.count-queue-name}")private String COUNT_QUEUE_NAME;@Value(value = "${mq.active.query-queue-name}")private String QUERY_QUEUE_NAME;@Autowiredprivate ActiveMQManager mqManager;@ApiOperation(value="發(fā)送解析文本", notes="發(fā)送解析文本", produces="application/json")@RequestMapping(value="/sendText", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)public String sendText(@RequestBody String text) {logger.info("發(fā)送的文本內(nèi)容：{}", text);try {mqManager.sendMsg(COUNT_QUEUE_NAME, text);} catch (Exception e){e.printStackTrace();logger.error(e.getMessage());}return "SUCESS";}@ApiOperation(value="查詢單詞計(jì)數(shù)", notes="查詢單詞計(jì)數(shù)", produces="application/json")@ApiImplicitParam(name = "word", value = "單詞", paramType = "query", required = true, dataType = "String")@RequestMapping(value="/queryWordCount", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)public String queryWordCount(@RequestBody String word) {logger.info("查詢單詞計(jì)數(shù)：{}", word);try {mqManager.sendMsg(QUERY_QUEUE_NAME, word);} catch (Exception e){e.printStackTrace();logger.error(e.getMessage());}return "SUCESS";} }

本接口示例了 @ApiOperation 和 @ApiImplicitParam 兩個(gè)注解的使用。

Swagger 通過(guò)注解定制接口對(duì)外展示的信息，這些信息包括接口名、請(qǐng)求方法、參數(shù)、返回信息等。更多注解類型：

@Api：修飾整個(gè)類，描述Controller的作用
@ApiOperation：描述一個(gè)類的一個(gè)方法，或者說(shuō)一個(gè)接口
@ApiParam：單個(gè)參數(shù)描述
@ApiModel：用對(duì)象來(lái)接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiImplicitParam：描述一個(gè)請(qǐng)求參數(shù)，可以配置參數(shù)的中文含義，還可以給參數(shù)設(shè)置默認(rèn)值
@ApiImplicitParams：描述由多個(gè) @ApiImplicitParam 注解的參數(shù)組成的請(qǐng)求參數(shù)列表

啟動(dòng) SpringBoot 應(yīng)用

SpringBoot 啟動(dòng)成功后，訪問(wèn) http://localhost:8080/swagger-ui.html

展開(kāi)類維度的接口列表，如 active-mq-producer，頁(yè)面會(huì)列出該類中定義的所有接口。點(diǎn)擊任意接口，可查看該接口的 url 路徑、請(qǐng)求類型、參數(shù)描述和返回碼說(shuō)明等信息。

點(diǎn)擊右上角的 “Try it out！”按鈕，錄入請(qǐng)求信息，點(diǎn)擊 Execute 按鈕完成一次請(qǐng)求調(diào)用！

Spring Security 中的配置

Spring Boot 項(xiàng)目中如果集成了 Spring Security，在不做額外配置的情況下，Swagger2 文檔會(huì)被攔截。解決方法是在 Security 的配置類中重寫 configure 方法添加白名單即可：

@Override public void configure ( WebSecurity web) throws Exception {web.ignoring().antMatchers("/swagger-ui.html").antMatchers("/v2/**").antMatchers("/swagger-resources/**"); }

參考文章

https://www.jianshu.com/p/c79f6a14f6c9

總結(jié)

以上是生活随笔為你收集整理的Spring Boot——集成Swagger2的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。

Spring
Boot

上一篇： Spring Boot——游戏成就系统设
下一篇： MyBatis Plus——启动/关闭控