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

javascript

SpringBoot 使用Swagger2打造在线接口文档（附源代码）

發(fā)布時間：2025/3/20 javascript 19 豆豆

生活随笔收集整理的這篇文章主要介紹了 SpringBoot 使用Swagger2打造在线接口文档（附源代码）小編覺得挺不錯的,現(xiàn)在分享給大家,幫大家做個參考.

點擊上方“好好學(xué)java”，選擇“置頂公眾號”

優(yōu)秀學(xué)習(xí)資源、干貨第一時間送達！

?精彩內(nèi)容?

java實戰(zhàn)練習(xí)項目教程

2018微服務(wù)資源springboot、springcloud、docker、dubbo實戰(zhàn)等傾心分享

2018年java架構(gòu)師全套學(xué)習(xí)教程

最新大數(shù)據(jù)培訓(xùn)完整視頻教程

2018年java最新全套培訓(xùn)學(xué)習(xí)教程

序言：編寫和維護接口文檔是每個程序員的職責(zé)，根據(jù)Swagger2可以快速幫助我們編寫最新的API接口文檔，再也不用擔(dān)心開會前仍忙于整理各種資料了，間接提升了團隊開發(fā)的溝通效率。此外，本教程還額外提供了UI漢化教程，去除閱讀官方英文界面的煩惱。（目前Swagger漢化教程是找不到的，因為官方手冊實在寫得太爛。。）

SpringBoot + Swagger2 UI界面-漢化教程

1.默認的英文界面UI

想必很多小伙伴都曾經(jīng)使用過Swagger，但是打開UI界面之后，卻是下面這樣的畫風(fēng)，純英文的界面并不太友好，作為國人還是習(xí)慣中文界面。

image

號稱世界最流行的API工具總不該不支持國際化屬性吧，樓主在官方使用手冊找到關(guān)于本地化和翻譯的說明：

image

也就是說，只要添加翻譯器和對于的譯文JS就可以顯示中文界面了。（使用IDEA 雙擊Shift 快速找到swagger-ui.html 入口文件）

image

2.定制中文界面

2.1 添加首頁和譯文

重點來了，在src/main/resources目錄下創(chuàng)建META-INF\resources目錄，然后創(chuàng)建一個名稱為"swagger-ui.html" 的HTML文件。如圖：

image

注意文件名不要起錯，接下來將下面這段內(nèi)容原封不動的拷貝進去。

<html> <head><meta?charset="UTF-8"><title>Swagger?UItitle><link?rel="icon"?type="image/png"?href="webjars/springfox-swagger-ui/images/favicon-32x32.png"?sizes="32x32"/><link?rel="icon"?type="image/png"?href="webjars/springfox-swagger-ui/images/favicon-16x16.png"?sizes="16x16"/><link?href='webjars/springfox-swagger-ui/css/typography.css'?media='screen'?rel='stylesheet'?type='text/css'/><link?href='webjars/springfox-swagger-ui/css/reset.css'?media='screen'?rel='stylesheet'?type='text/css'/><link?href='webjars/springfox-swagger-ui/css/screen.css'?media='screen'?rel='stylesheet'?type='text/css'/><link?href='webjars/springfox-swagger-ui/css/reset.css'?media='print'?rel='stylesheet'?type='text/css'/><link?href='webjars/springfox-swagger-ui/css/print.css'?media='print'?rel='stylesheet'?type='text/css'/><script?src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/lodash.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/backbone-min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/swagger-ui.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/marked.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lib/swagger-oauth.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/springfox.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lang/translator.js'?type='text/javascript'>script><script?src='webjars/springfox-swagger-ui/lang/zh-cn.js'?type='text/javascript'>script>head><body?class="swagger-p"> <div?id='header'><div?class="swagger-ui-wrap"><a?id="logo"?href="http://swagger.io">![](webjars/springfox-swagger-ui/images/logo_small.png)<span?class="logo__title">swaggerspan>a><form?id='api_selector'><div?class='input'><select?id="select_baseUrl"?name="select_baseUrl">select>div><div?class='input'><input?placeholder="http://example.com/api"?id="input_baseUrl"?name="baseUrl"?type="text"/>div><div?id='auth_container'>div><div?class='input'><a?id="explore"?class="header__btn"?href="#"?data-sw-translate>Explorea>div>form>div> div><div?id="message-bar"?class="swagger-ui-wrap"?data-sw-translate>?div> <div?id="swagger-ui-container"?class="swagger-ui-wrap">div> body> html>

OK 大功告成我們訪問 http://localhost:8080/swagger-ui.html 看看顯示效果：

imageimage

注：關(guān)于國際化，直接在Github下載好Swagger-UI的源碼，將swagger-ui.html替換成上文，直接發(fā)布到Maven私服倉庫，使用效果更佳。

2.2 更詳細的譯文翻譯（非必需）

如果想進一步調(diào)整譯文，可以在META-INF\resources\webjars\springfox-swagger-ui\lang 目錄下添加zh-cn.js文件.

image

然后在譯文（zh-cn.js ）根據(jù)個人喜好來添加翻譯內(nèi)容，如下

'use?strict';/*?jshint?quotmark:?double?*/ window.SwaggerTranslator.learn({"Warning:?Deprecated":"警告：已過時","Implementation?Notes":"實現(xiàn)備注","Response?Class":"響應(yīng)類","Status":"狀態(tài)","Parameters":"參數(shù)","Parameter":"參數(shù)","Value":"值","Description":"描述","Parameter?Type":"參數(shù)類型","Data?Type":"數(shù)據(jù)類型","Response?Messages":"響應(yīng)消息","HTTP?Status?Code":"HTTP狀態(tài)碼","Reason":"原因","Response?Model":"響應(yīng)模型","Request?URL":"請求URL","Response?Body":"響應(yīng)體","Response?Code":"響應(yīng)碼","Response?Headers":"響應(yīng)頭","Hide?Response":"隱藏響應(yīng)","Headers":"頭","Try?it?out!":"試一下！","Show/Hide":"顯示/隱藏","List?Operations":"顯示操作","Expand?Operations":"展開操作","Raw":"原始","can't?parse?JSON.??Raw?result":"無法解析JSON.?原始結(jié)果","Example?Value":"示例","Click?to?set?as?parameter?value":"點擊設(shè)置參數(shù)","Model?Schema":"模型架構(gòu)","Model":"模型","apply":"應(yīng)用","Username":"用戶名","Password":"密碼","Terms?of?service":"服務(wù)條款","Created?by":"創(chuàng)建者","See?more?at":"查看更多：","Contact?the?developer":"聯(lián)系開發(fā)者","api?version":"api版本","Response?Content?Type":"響應(yīng)Content?Type","Parameter?content?type:":"參數(shù)類型:","fetching?resource":"正在獲取資源","fetching?resource?list":"正在獲取資源列表","Explore":"瀏覽","Show?Swagger?Petstore?Example?Apis":"顯示?Swagger?Petstore?示例?Apis","Can't?read?from?server.??It?may?not?have?the?appropriate?access-control-origin?settings.":"無法從服務(wù)器讀取?？赡軟]有正確設(shè)置access-control-origin。","Please?specify?the?protocol?for":"請指定協(xié)議：","Can't?read?swagger?JSON?from":"無法讀取swagger?JSON于","Finished?Loading?Resource?Information.?Rendering?Swagger?UI":"已加載資源信息。正在渲染Swagger?UI","Unable?to?read?api":"無法讀取api","from?path":"從路徑","server?returned":"服務(wù)器返回" });

SpringBoot + Swagger2 使用教程

1、引入依賴

????<dependencies><dependency>?<groupId>org.springframework.bootgroupId><artifactId>spring-boot-starter-webartifactId>dependency><dependency><groupId>io.springfoxgroupId><artifactId>springfox-swagger2artifactId><version>2.7.0version>dependency><dependency><groupId>io.springfoxgroupId><artifactId>springfox-swagger-uiartifactId><version>2.7.0version>dependency><dependency>?<groupId>org.springframework.bootgroupId><artifactId>spring-boot-devtoolsartifactId>dependency><dependency><groupId>org.springframework.bootgroupId><artifactId>spring-boot-starter-testartifactId><scope>testscope>dependency>dependencies>

2、添加配置

@Configuration?//標(biāo)記配置類 @EnableSwagger2?//開啟在線接口文檔 public?class?Swagger2Config?{/***?添加摘要信息(Docket)*/@Beanpublic?Docket?controllerApi()?{return?new?Docket(DocumentationType.SWAGGER_2).apiInfo(new?ApiInfoBuilder().title("標(biāo)題：某公司_用戶信息管理系統(tǒng)_接口文檔").description("描述：用于管理集團旗下公司的人員信息,具體包括XXX,XXX模塊...").contact(new?Contact("一只襪子",?null,?null)).version("版本號:1.0").build()).select().apis(RequestHandlerSelectors.basePackage("com.hehe.controller")).paths(PathSelectors.any()).build();} }

3、編寫接口文檔

Swagger2 基本使用：

@Api 描述類/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的參數(shù)
@ApiImplicitParams 描述方法的參數(shù)(Multi-Params)
@ApiIgnore 忽略某類/方法/參數(shù)的文檔

Swagger2 使用注解來編寫文檔：

Swagger2編寫接口文檔相當(dāng)簡單，只需要在控制層（Controller）添加注解來描述接口信息即可。例如：

package?com.hehe.controller;@Api("用戶信息管理") @RestController @RequestMapping("/user/*") public?class?UserController?{private?final?static?List?userList?=?new?ArrayList<>();{userList.add(new?User("1",?"admin",?"123456"));userList.add(new?User("2",?"jacks",?"111111"));}@ApiOperation("獲取列表")@GetMapping("list")public?List?userList()?{return?userList;}@ApiOperation("新增用戶")@PostMapping("save")public?boolean?save(User?user)?{return?userList.add(user);}@ApiOperation("更新用戶")@ApiImplicitParam(name?=?"user",?value?=?"單個用戶信息",?dataType?=?"User")@PutMapping("update")public?boolean?update(User?user)?{return?userList.remove(user)?&&?userList.add(user);}@ApiOperation("批量刪除")@ApiImplicitParam(name?=?"users",?value?=?"N個用戶信息",?dataType?=?"List")@DeleteMapping("delete")public?boolean?delete(@RequestBody?List?users)?{return?userList.removeAll(users);} }package?com.hehe.entity;public?class?User?{private?String?userId;private?String?username;private?String?password;public?User()?{}public?User(String?userId,?String?username,?String?password)?{this.userId?=?userId;this.username?=?username;this.password?=?password;}@Overridepublic?boolean?equals(Object?o)?{if?(this?==?o)?{return?true;}if?(o?==?null?||?getClass()?!=?o.getClass())?{return?false;}User?user?=?(User)?o;return?userId?!=?null???userId.equals(user.userId)?:?user.userId?==?null;}@Overridepublic?int?hashCode()?{int?result?=?userId?!=?null???userId.hashCode()?:?0;result?=?31?*?result?+?(username?!=?null???username.hashCode()?:?0);result?=?31?*?result?+?(password?!=?null???password.hashCode()?:?0);return?result;}public?String?getUserId()?{return?userId;}public?void?setUserId(String?userId)?{this.userId?=?userId;}public?String?getUsername()?{return?username;}public?void?setUsername(String?username)?{this.username?=?username;}public?String?getPassword()?{return?password;}public?void?setPassword(String?password)?{this.password?=?password;} }

4、查閱接口文檔

編寫文檔完成之后，啟動當(dāng)前項目，在瀏覽器打開：
[ http://localhost:8080/swagger-ui.html ] , 看到效果如下：

image

來看看save 方法的具體描述，可以看到Swagger 2.7.0 版本對參數(shù)列表進行了改版，直接輸入?yún)?shù)，更方便進行測試操作：

image

5、測試接口

Swagger2的強大之處不僅在于快速生成整潔優(yōu)雅的RestAPI文檔，同時支持接口方法的測試操作（類似于客戶端PostMan）。

以查詢用戶列表為例，無參數(shù)輸入，直接點擊“試一下”按鈕：

image

然后可以看到以JSON格式返回的用戶列表信息，很方便有木有：

image

好了，關(guān)于Swagger2在項目中的使用教程就到這里。

源碼下載：https://github.com/yizhiwazi/springboot-socks/tree/master/springboot-swagger2
專題閱讀：https://www.jianshu.com/p/964370d9374e

作者：yizhiwazi
鏈接：https://www.jianshu.com/p/7e543f0f0bd8

總結(jié)

以上是生活随笔為你收集整理的SpringBoot 使用Swagger2打造在线接口文档（附源代码）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

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

上一篇： SpringBoot 使用WebSock
下一篇： gradle idea java ssm

javascript

SpringBoot 使用Swagger2打造在线接口文档（附源代码）

SpringBoot + Swagger2 UI界面-漢化教程

1.默認的英文界面UI

2.定制中文界面

2.1 添加首頁和譯文

2.2 更詳細的譯文翻譯（非必需）

SpringBoot + Swagger2 使用教程

1、 引入依賴

2、 添加配置

3、編寫接口文檔

Swagger2 基本使用：

Swagger2 使用注解來編寫文檔：

4、 查閱接口文檔

5、測試接口

總結(jié)

1、引入依賴

2、添加配置

3、編寫接口文檔

4、查閱接口文檔