SpringBoot第十五篇:swagger構建優雅文件
作者:追夢1819
原文:https://www.cnblogs.com/yanfei1819/p/11007470.html
版權宣告:本文為博主原創文章,轉載請附上博文連結!
引言
前面的十四篇文介紹了 SpringBoot 的一些基本和常用的功能。後面,我們將介紹 SpringBoot 的高階的功能、框架原理以及使用技巧。
一個專案組可能由前端、後端、安卓、IOS等眾多的開發人員或者眾多開發團隊組成。內部的 API 共同成本巨大。主要體現在幾個方面:
- 介面多且複雜;
- 細節之處繁雜:通訊協議、引數、返回值、介面說明、路徑等;
- 介面的維護。功能介面是隨著時間迭代升級的,因此這增加了介面文件的管理成本。
因此,團隊內部的溝通,一直都是開發人員的一個痛點。而手動編寫 api 文件,不僅效率低,而且容易遺漏、不能及時同步更新。swagger 框架很好的解決了此問題。
swagger簡介
swagger 優雅的解決了這個問題。它是一個功能強大的API框架,它的整合非常簡單,不僅提供了線上文件的查閱,而且還提供了線上文件的測試。swagger 是一個規範和完整的框架,用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法,引數和模型緊密整合到伺服器端的程式碼,允許API來始終保持同步。swagger 讓部署管理和使用功能強大的 API 從未如此簡單。
版本資訊
- JDK:1.8
- SpringBoot :2.1.4.RELEASE
- maven:3.3.9
- swagger2:2.4.0
- swagger-bootstrap-ui:1.7
- IDEA:2019.1.1
swagger 常用註解
swagger 通過註解表明該介面會生成文件,包括介面名、請求方法、引數、返回資訊的等等。
@Api:修飾整個類,描述Controller的作用
@ApiOperation:描述一個類的一個方法,或者說一個介面
@ApiParam:單個引數描述
@ApiModel:用物件來接收引數
@ApiProperty:用物件接收引數時,描述物件的一個欄位
@ApiResponse:HTTP響應其中1個描述
@ApiResponses:HTTP響應整體描述
@ApiIgnore:使用該註解忽略這個API
@ApiError :發生錯誤返回的資訊
@ApiImplicitParam 一個引數
@ApiImplicitParams 多個引數
swagger使用
為了更加形象說明 swagger 的使用,下面建立一個例項專案以作演示。
首先,引入 maven 依賴:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- swagger用於定義API文件 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
然後,配置 swagger:
package com.yanfei1819.swaggerdemo;
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
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yanfei1819.swaggerdemo.controller"))
// .paths(AppUtility.isProd() ? PathSelectors.none() : PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("測試swagger")
.description("展示swagger介面")
.termsOfServiceUrl("http://localhost:8084/swagger-ui.html")
.contact(new Contact("追夢1819", "http://localhost:8084/swagger-ui.html", "[email protected]"))
.version("1.0")
.build();
}
}
下一步,建立幾個測試方法:
package com.yanfei1819.swaggerdemo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.annotations.ApiIgnore;
/**
* Created by 追夢1819 on 2019-05-06.
*/
@Controller
@RequestMapping("/swagger-a")
@Api(value = "測試第一個controller")
public class SwaggerAController {
@ApiOperation(value = "controllerA的測試方法一",notes = "controllerA的測試方法一")
@GetMapping("/test1")
public void test1(){}
@ApiOperation(value = "controllerA的測試方法二",notes = "controllerA的測試方法二")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "使用者姓名", required = true, dataType = "String"),
@ApiImplicitParam(name = "password", value = "使用者密碼", required = true, dataType = "String")
})
@PostMapping("/test2")
public void test2(String name,String password){}
@ApiOperation(value = "controllerA的測試方法三",notes = "controllerA的測試方法三")
@ApiImplicitParam(name = "name", value = "使用者姓名", required = true, dataType = "String")
@GetMapping("/test3")
public void test3(String name){}
// 該介面忽略
@ApiIgnore
@GetMapping("/test4")
public void test4(String name){}
}
最後,訪問:http://localhost:8084/swagger-ui.htm
,生成的相應的介面:
優化swagger介面
swagger 原生的介面談不上美觀。swagger-bootstrap-ui
是springfox-swagger
的增強UI實現,為Java開發者在使用 swagger 的時候,能擁有一份簡潔、強大的介面文件體驗。
swagger-bootstrap-ui
提供兩大核心功能:文件說明 和 線上除錯,以下作說明。
在以上例項的基礎上,引入maven依賴即可:
<!--美化swagger-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.7</version>
</dependency>
然後,訪問 http://localhost:8084/doc.html
,看看效果:
總結
其實對於作者來說,我並不喜歡這種這種編碼風格。雖然生成了 spi 文件,但是其註解對介面的汙染較大。算是事有利弊吧,主要衡量利弊輕重。
原始碼:我的GitHub
相關推薦
SpringBoot第十五篇:swagger構建優雅文件
作者:追夢1819 原文:https://www.cnblogs.com/yanfei1819/p/11007470.html 版權宣告:本文為博主原創文章,轉載請附上博文連結! 引言 前面的十四篇文介紹了 SpringBoot 的一些基本和常用的功能。後面,我們將介紹 SpringBoot 的高階的功
一起來學SpringBoot | 第十五篇:actuator與spring-boot-admin 可以說的祕密
SpringBoot 是為了簡化 Spring 應用的建立、執行、除錯、部署等一系列問題而誕生的產物,自動裝配的特性讓我們可以更好的關注業務本身而不是外部的XML配置,我們只需遵循規範,引入相關的依賴就可以輕易的搭建出一個 WEB 工程 一起來學Spr
轉載:SpringBoot非官方教程 | 第十五篇:Springboot整合RabbitMQ
這篇文章帶你瞭解怎麼整合RabbitMQ伺服器,並且通過它怎麼去傳送和接收訊息。我將構建一個springboot工程,通過RabbitTemplate去通過MessageListenerAdapter去訂閱一個POJO型別的訊息。 準備工作 15min ID
SpringBoot非官方教程 | 第十五篇:Springboot整合RabbitMQ
這篇文章帶你瞭解怎麼整合RabbitMQ伺服器,並且通過它怎麼去傳送和接收訊息。我將構建一個springboot工程,通過RabbitTemplate去通過MessageListenerAdapter去訂閱一個POJO型別的訊息。 準備工作 15min ID
一起來學SpringBoot | 第十一篇:整合Swagger線上除錯
SpringBoot 是為了簡化 Spring 應用的建立、執行、除錯、部署等一系列問題而誕生的產物,自動裝配的特性讓我們可以更好的關注業務本身而不是外部的XML配置,我們只需遵循規範,引入相關的依賴就可以輕易的搭建出一個 WEB 工程 隨著網際網路技
第十五篇:JavaScript 之 Dom操作
頁面 對象模型 面向 方法 bsp log gpo eva div 一、後臺管理頁面布局 二、JavaScript函數 三、eval以及時間操作 四、JavaScript作用域 五、JavaScript面向對象模型 六、DOM選擇器 七、DOM事件操作 八、DOM綁定事件的
卜若的程式碼筆記系列-Web系列-SpringBoot-第十二章:Swagger的批註詳解-3212
1. @ApiOperation("swaggerTest") 用來描述當前的api的簡略資訊 我來解釋下為什麼會出現這麼多比如DELETE,GET,HEAED啥的請求,因為swagger預設將所有請求全部顯示出來,為了解決這種情況,我們其實可以將這個api單獨
一起來學SpringBoot | 第十四篇:強大的 actuator 服務監控與管理
SpringBoot 是為了簡化 Spring 應用的建立、執行、除錯、部署等一系列問題而誕生的產物,自動裝配的特性讓我們可以更好的關注業務本身而不是外部的XML配置,我們只需遵循規範,引入相關的依賴就可以輕易的搭建出一個 WEB 工程 actuato
第十五篇:前輩opencv學習入門經驗
首先,搞影象處理,熟悉影象演算法是必經之路,如果上過影象處理這門課的話,再好不過。如果沒有,我推薦中科院研究生院劉定生老師的數字影象處理與分析(視訊),這位老師上課引人入勝,值得推薦。其次,在這個階段,配套的書籍自然是《岡薩雷斯版數字影象處理》這本書,最好同時用matlab軟體,模擬每一個影象演算法案例,推薦
一起來學SpringBoot | 第十九篇:輕鬆搞定資料驗證(一)
SpringBoot是為了簡化Spring應用的建立、執行、除錯、部署等一系列問題而誕生的產物,自動裝配的特性讓我們可以更好的關注業務本身而不是外部的XML配置,我們只需遵循規範,引入相關的依賴就可以輕易的搭建出一個 WEB 工程 對於任何一個
Python 學習 第十五篇:模塊搜索路徑和包導入
部分 blank 所有 python 環境變量 bsp 引入 html pytho 在導入自定義的模塊時,除了指定模塊名之外,也需要指定目錄,由於Python把目錄稱作包,因此,這類導入被稱為包導入。包導入把計算機上的目錄變成Python的命名空間,而目錄中所包含的子目錄和
SpringBoot第十一篇:SpringBoot+MyBatis+Thymelaf實現CRUD
作者:追夢1819 原文:https://www.cnblogs.com/yanfei1819/p/10936304.html 版權宣告:本文為博主原創文章,轉載請附上博文連結! 引言 總結前面幾章,我們瞭解了 SpringBoot 的基本用法及其配置,整合各大 ORM 框架,並瞭解了 Thymelaf
SpringBoot第十二篇:整合jsp
作者:追夢1819 原文:https://www.cnblogs.com/yanfei1819/p/10953600.html 版權宣告:本文為博主原創文章,轉載請附上博文連結! 引言 SpringBoot 雖然官方推薦使用 thymelaf 模板引擎,但是也支援jsp,只不過需要做一些修改。本文將講解
SpringBoot第十四篇:統一異常處理
作者:追夢1819 原文:https://www.cnblogs.com/yanfei1819/p/10984081.html 版權宣告:本文為博主原創文章,轉載請附上博文連結! 引言 本文將談論 SpringBoot 的預設錯誤處理機制,以及如何自定義錯誤響應。 版本資訊 JDK:1.8 Spri
SpringBoot第十六篇:自定義starter
作者:追夢1819 原文:https://www.cnblogs.com/yanfei1819/p/11058502.html 版權宣告:本文為博主原創文章,轉載請附上博文連結! 前言 這一段時間專案趕進度,故該系列部落格更新沒有之前那麼頻繁,望諒解。 SpringBoot 用起來方便,它預設集成了
SpringBoot第十七篇:定時任務
作者:追夢1819 原文:https://www.cnblogs.com/yanfei1819/p/11076555.html 版權宣告:本文為博主原創文章,轉載請附上博文連結! 引言 相信大家對定時任務很熟悉,其重要性也不言而喻。定時發簡訊、定時批量操作、定時統計資料等,都離不開定時任務。本文將講解定
跟我學SpringCloud | 第十五篇:微服務利劍之APM平臺(一)Skywalking
目錄 SpringCloud系列教程 | 第十五篇:微服務利劍之APM平臺(一)Skywalking 1. Skywalking概述 2. Skywalking主要功能 3. Skywalking主要特性
PowerBI開發 第十五篇:Power BI的行級安全
Power BI支援行級安全(Row-Level Security,RLS)的許可權控制,用於限制使用者對Dashboard、報表和DataSet的訪問。使用者瀏覽的報表是相同的,但是看到的資料卻是不同的。 RLS內部通過DAX函式 username() 和 userprincipalname()來實現,R
(轉)第十一篇:springboot集成swagger2,構建優雅的Restful API
html 風格 lan round amt select() hash 指定 model 聲明:本部分內容均轉自於方誌明博友的博客,因為本人很喜歡他的博客,所以一直在學習,轉載僅是記錄和分享,若也有喜歡的人的話,可以去他的博客首頁看:http://blog.csdn.n
轉載:SpringBoot非官方教程 | 第十一篇:springboot整合swagger2,構建優雅的Restful API
swagger,中文“拽”的意思。它是一個功能強大的api框架,它的整合非常簡單,不僅提供了線上文件的查閱,而且還提供了線上文件的測試。另外swagger很容易構建restful風格的api,簡單優雅帥氣,正如它的名字。 一、引入依賴 <depend