當前位置：
首頁 >
前端技术
> javascript
>内容正文
javascript
SpringBoot 使用Swagger2打造在线接口文档（附源代码）
生活随笔
收集整理的這篇文章主要介紹了
SpringBoot 使用Swagger2打造在线接口文档（附源代码）
小編覺得挺不錯的,現在分享給大家,幫大家做個參考.
點擊上方“好好學java”，選擇“置頂公眾號”
優秀學習資源、干貨第一時間送達！
?精彩內容?
java實戰練習項目教程
2018微服務資源springboot、springcloud、docker、dubbo實戰等傾心分享
2018年java架構師全套學習教程
最新大數據培訓完整視頻教程
2018年java最新全套培訓學習教程
序言：編寫和維護接口文檔是每個程序員的職責，根據Swagger2可以快速幫助我們編寫最新的API接口文檔，再也不用擔心開會前仍忙于整理各種資料了，間接提升了團隊開發的溝通效率。此外，本教程還額外提供了UI漢化教程，去除閱讀官方英文界面的煩惱。（目前Swagger漢化教程是找不到的，因為官方手冊實在寫得太爛。。）
SpringBoot + Swagger2 UI界面-漢化教程
1.默認的英文界面UI
想必很多小伙伴都曾經使用過Swagger，但是打開UI界面之后，卻是下面這樣的畫風，純英文的界面并不太友好，作為國人還是習慣中文界面。
image號稱世界最流行的API工具總不該不支持國際化屬性吧，樓主在官方使用手冊找到關于本地化和翻譯的說明：
image也就是說，只要添加翻譯器和對于的譯文JS就可以顯示中文界面了。（使用IDEA 雙擊Shift 快速找到swagger-ui.html 入口文件）
image2.定制中文界面
2.1 添加首頁和譯文
重點來了，在src/main/resources目錄下創建META-INF\resources目錄，然后創建一個名稱為"swagger-ui.html" 的HTML文件。如圖：
image注意文件名不要起錯，接下來將下面這段內容原封不動的拷貝進去。
<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"><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注：關于國際化，直接在Github下載好Swagger-UI的源碼，將swagger-ui.html替換成上文，直接發布到Maven私服倉庫，使用效果更佳。
2.2 更詳細的譯文翻譯（非必需）
如果想進一步調整譯文，可以在META-INF\resources\webjars\springfox-swagger-ui\lang 目錄下添加zh-cn.js文件.
image然后在譯文（zh-cn.js ）根據個人喜好來添加翻譯內容，如下
'use?strict';/*?jshint?quotmark:?double?*/ window.SwaggerTranslator.learn({"Warning:?Deprecated":"警告：已過時","Implementation?Notes":"實現備注","Response?Class":"響應類","Status":"狀態","Parameters":"參數","Parameter":"參數","Value":"值","Description":"描述","Parameter?Type":"參數類型","Data?Type":"數據類型","Response?Messages":"響應消息","HTTP?Status?Code":"HTTP狀態碼","Reason":"原因","Response?Model":"響應模型","Request?URL":"請求URL","Response?Body":"響應體","Response?Code":"響應碼","Response?Headers":"響應頭","Hide?Response":"隱藏響應","Headers":"頭","Try?it?out!":"試一下！","Show/Hide":"顯示/隱藏","List?Operations":"顯示操作","Expand?Operations":"展開操作","Raw":"原始","can't?parse?JSON.??Raw?result":"無法解析JSON.?原始結果","Example?Value":"示例","Click?to?set?as?parameter?value":"點擊設置參數","Model?Schema":"模型架構","Model":"模型","apply":"應用","Username":"用戶名","Password":"密碼","Terms?of?service":"服務條款","Created?by":"創建者","See?more?at":"查看更多：","Contact?the?developer":"聯系開發者","api?version":"api版本","Response?Content?Type":"響應Content?Type","Parameter?content?type:":"參數類型:","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.":"無法從服務器讀取。可能沒有正確設置access-control-origin。","Please?specify?the?protocol?for":"請指定協議：","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":"服務器返回" });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?//標記配置類 @EnableSwagger2?//開啟在線接口文檔 public?class?Swagger2Config?{/***?添加摘要信息(Docket)*/@Beanpublic?Docket?controllerApi()?{return?new?Docket(DocumentationType.SWAGGER_2).apiInfo(new?ApiInfoBuilder().title("標題：某公司_用戶信息管理系統_接口文檔").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 描述方法的參數
@ApiImplicitParams 描述方法的參數(Multi-Params)
@ApiIgnore 忽略某類/方法/參數的文檔
Swagger2 使用注解來編寫文檔：
Swagger2編寫接口文檔相當簡單，只需要在控制層（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、 查閱接口文檔
編寫文檔完成之后，啟動當前項目，在瀏覽器打開：
[ http://localhost:8080/swagger-ui.html ] , 看到效果如下：
來看看save 方法的具體描述，可以看到Swagger 2.7.0 版本對參數列表進行了改版，直接輸入參數，更方便進行測試操作：
image5、測試接口
Swagger2的強大之處不僅在于快速生成整潔優雅的RestAPI文檔，同時支持接口方法的測試操作（類似于客戶端PostMan）。
以查詢用戶列表為例，無參數輸入，直接點擊“試一下”按鈕：
image然后可以看到以JSON格式返回的用戶列表信息，很方便有木有：
image好了，關于Swagger2在項目中的使用教程就到這里。
源碼下載：https://github.com/yizhiwazi/springboot-socks/tree/master/springboot-swagger2
專題閱讀：https://www.jianshu.com/p/964370d9374e
作者：yizhiwazi
鏈接：https://www.jianshu.com/p/7e543f0f0bd8
推薦閱讀
1.?解密微信小程序登錄全過程（ssm實現）
2.?springmvc入門
3.?java高并發容器詳情
4.?重溫javaweb過濾器filter
附上熱門QQ群，存放資源和歷史資料，2000容量（低門檻付費群），長按二維碼入群
總結
以上是生活随笔為你收集整理的SpringBoot 使用Swagger2打造在线接口文档（附源代码）的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： SpringBoot 使用WebSock
- 下一篇： 一篇文章搞定，SpringBoot 创建