整合營銷服務商

          電腦端+手機端+微信端=數據同步管理

          免費咨詢熱線:

          pring Boot 開發者必備的 Swagger

          pring Boot 開發者必備的 Swagger 集成技巧

          wagger 最初作為一套規范而問世,后來在 2015 年捐贈給Linux基金會后演變為 OpenAPI 規范(OAS)。這次轉變標志著 API 文檔編寫和互操作性的一次進步,使其向 OpenAPI 3.0 過渡。在現今的行業討論中,提到 Swagger 通常指的是 SmartBear Software 開發的一套用于實現 OpenAPI 規范的工具。這套工具包括開源、免費和商業工具的組合,支持 API 生命周期的各個開發階段。

          • 什么是 Swagger?- 全面介紹Swagger 的作用和優點

          使用 Swagger 工具的核心在于采用設計優先的原則,把生成 API 文檔視為開發過程的基石。開發者可以根據自己的偏好選擇方法:一些人偏好使用 Swagger Editor 在線創建 API 文檔,而另一些人則偏好編寫代碼時注釋,讓文檔自動生成。這兩種方法都為簡化和優化開發過程提供了路徑。

          • 如何使用 Swagger Editor 編寫 API 文檔

          其中,Spring Boot 項目的集成已表現出良好的適應性,SpringfoxSpringdoc作為領先的開源庫促進了這一整合。

          Springfox與Springdoc深入探討

          Springfox:借鑒傳統

          Springfox 作為 Swagger 的 Java 實現,幫助生成兼容 Swagger 2.0 規范的 API 文檔。它通過一系列注解為開發者提供了生成相應 API 文檔的能力。此外,Springfox 還提供了可擴展接口,允許定制文檔生成過程以滿足特殊需求。盡管它因支持 Swagger 2 規范而被廣泛使用,但更新速度緩慢和與新版本 Spring Boot 的兼容問題一直是人們關心的問題。

          Springdoc:新興前沿

          與此同時,Springdoc 因其與 Spring Boot 的深度集成以及支持 OpenAPI 3.0 規范而脫穎而出。它涵蓋了更廣泛的Spring項目,包括 Spring WebMvc、Spring WebFlux、Spring Data Rest 和 Spring Security。以快速更新和生成 OpenAPI 3.0 規范文檔而聞名,Springdoc 也為用戶提供了自定義文檔生成過程的能力,盡管目前支持的插件較少。

          使用Springdoc-openapi發展文檔

          springdoc-openapi Java 庫為 Spring Boot 應用中自動化生成 API 文檔提供了創新解決方案。它通過審查應用的 Spring 配置、類結構和注釋來推斷 API 語義,產生格式化的 JSON/YAML 和 HTML 文檔。

          快速開始 Springdoc

          1. 安裝依賴: 確認在項目的 POM 文件中加入最新版的springdoc-openapi-ui依賴。
          2. 啟用Swagger: 在application.yml文件中修改配置以根據需要啟用或禁用 Swagger 3。
          3. 配置SwaggerController: 實現一個 Swagger3Config 類來配置 API 分組,并為操作添加自定義參數或頭部。
          4. 注釋實體類: 對你的實體類使用 Swagger 的@Schema注釋,以便準確地進行文檔編寫。
          5. 控制器注釋: 通過為控制器方法添加 Swagger 的@Operation@Parameter注釋來精確定義 API。

          訪問 Swagger UI

          通過訪問http://server:port/context-path/swagger-ui.html來查看生成的 Swagger 文檔。

          其他方式

          雖然springdoc-openapi為 API 文檔提供了無與倫比的支持,但將其與 Apifox 整合為分享和同步 API 細節提供了一個吸引人的途徑。Apifox 提供了一個全面的平臺,支持 API 設計、文檔、測試和協作功能,能夠自動解析代碼注釋并從 Javadoc、KDoc 和 ScalaDoc 生成 API 文檔。通過使用 IntelliJ IDEA 的 Apifox Helper 插件,開發人員可以在不離開 IDE 的情況下與 Apifox 項目同步他們的文檔。此外,Apifox 通過其直觀的UI豐富了 API 管理體驗,支持從 IDEA 直接啟動內部測試和導出文檔。

          • 如何使用 Apifox 自動生成 API 接口文檔 - 一份詳細指南

          對于希望提升 API 文檔和協作工作流的開發人員,采用 Apifox 與 Springdoc-openapi 可能成為改變游戲規則的策略。

          、前言

          Spring Boot作為當前最為流行的Java web開發腳手架,越來越多的開發者選擇用其來構建企業級的RESTFul API接口。這些接口不但會服務于傳統的web端(b/s),也會服務于移動端。在實際開發過程中,這些接口還要提供給開發測試進行相關的白盒測試,那么勢必存在如何在多人協作中共享和及時更新API開發接口文檔的問題。

          使用 Swagger 集成文檔具有以下幾個優勢:

          • 功能豐富 :支持多種注解,自動生成接口文檔界面,支持在界面測試API接口功能;
          • 及時更新 :開發過程中花一點寫注釋的時間,就可以及時的更新API文檔,省心省力;
          • 整合簡單 :通過添加pom依賴和簡單配置,內嵌于應用中就可同時發布API接口文檔界面,不需要部署獨立服務。

          接下來,我們通過Spring Boot來整合Swagger實現在線API文檔的功能,本文用的是SpringFox Swagger2,版本2.9.2(最新版本是3.0.0,但是在我測試是swagger-ui.html頁面一直出不來,在https://mvnrepository.com/上也可以看到,2.9.2是目前使用最多的版本)

          二、創建Spring Boot工程

          我用的開發工具是IDEA,通過IDEA快速創建一個Spring Boot工程,創建時,只需勾選web依賴選項就成,不勾選也沒關系,后面在pom.xml中配置也是一樣的。注意創建工程時,工程名稱都要是小寫。

          添加Swagger的兩個依賴

          <!-- swagger -->
          <dependency>
              <groupId>io.springfox</groupId>
              <artifactId>springfox-swagger2</artifactId>
              <version>2.9.2</version>
          </dependency>
          <dependency>
              <groupId>io.springfox</groupId>
              <artifactId>springfox-swagger-ui</artifactId>
              <version>2.9.2</version>
          </dependency>
          

          三、添加配置類

          添加一個swagger 配置類,在工程下新建 config 包并添加一個 SwaggerConfig 配置類SwaggerConfig.java。

          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.ApiInfo;
          import springfox.documentation.spi.DocumentationType;
          import springfox.documentation.spring.web.plugins.Docket;
          import springfox.documentation.swagger2.annotations.EnableSwagger2;
          
          @Configuration
          @EnableSwagger2
          public class SwaggerConfig {
          
              @Bean
              public Docket createRestApi(){
                  return new Docket(DocumentationType.SWAGGER_2)
                          .apiInfo(apiInfo())
                          .select()
                          .apis(RequestHandlerSelectors.any())
                          .paths(PathSelectors.any())
                          .build();
              }
          
              private ApiInfo apiInfo(){
                  return new ApiInfoBuilder()
                          .title("在線API文檔")
                          .description("This is a restful api document of demo")
                          .version("1.0")
                          .build();
              }
          
          }
          

          以上就已經完成了Swagger的配置,是不是很簡潔輕松。

          四、創建一個測試Controller來驗證配置

          添加一個控制器,在工程下新建 controller包并添加一個 HelloController控制器HelloController.java。

          package com.louis.springboot.demo.controller;
          
          import org.springframework.web.bind.annotation.GetMapping;
          import org.springframework.web.bind.annotation.RequestParam;
          import org.springframework.web.bind.annotation.RestController;
          
          import io.swagger.annotations.Api;
          import io.swagger.annotations.ApiOperation;
          import io.swagger.annotations.ApiParam;
          
          /* 類注解 */
          @Api
          @RestController
          public class HelloController {
          
              /* 方法注解 */
              @ApiOperation(value="desc of method", notes="")
              @GetMapping(value="/hello")
              public Object hello( @ApiParam(value="desc of param" , required=true ) @RequestParam String name) {
                  return "Hello " + name + "!";
              }
          }
          

          五、編譯運行測試

          啟動工程, 打開瀏覽器,訪問:http://localhost:8080/swagger-ui.html,進入swagger接口文檔界面。


          完畢收工,這樣管理API接口很方便,并且是和代碼實時更新的,不用煩心再去寫接口文檔啦。

          附錄:Swagger常用注解

          API

          使用位置

          @Api

          用于controller類上,表示標識這個類是swagger的資源

          @ApiOperation

          用在controller的方法上,表示一個http請求的操作

          @ApiParam

          方法中的參數注釋

          @ApiResponses

          用在controller的方法上

          @ApiResponse

          用在 @ApiResponses里邊

          @ApiImplicitParams

          用在controller的方法上

          @ApiImplicitParam

          用在@ApiImplicitParams的方法里邊

          @ApiModel

          用在返回對象類上

          WEB項目開發中碰到的問題千奇百怪。

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

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

          SpringBoot + Swagger2 UI界面-漢化教程

          1.默認的英文界面UI

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

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

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

          2.定制中文界面

          2.1 添加首頁和譯文

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

          注意文件名不要起錯,接下來將下面這段內容原封不動的拷貝進去。

          <!DOCTYPE html>
          <html>
          <head>
           <meta charset="UTF-8">
           <title>Swagger UI</title>
           <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-section">
          <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">swagger</span></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>Explore</a></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 看看顯示效果:

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

          2.2 更詳細的譯文翻譯(非必需)

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

          然后在譯文(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":"服務器返回"
          });
          
          

          ===========接下來,正式進入Swagger2的使用教程===========

          SpringBoot + Swagger2 使用教程

          1. 引入依賴

           <!--依賴管理 -->
           <dependencies>
           <dependency> <!--添加Web依賴 -->
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-web</artifactId>
           </dependency>
           <dependency><!--添加Swagger依賴 -->
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.7.0</version>
           </dependency>
           <dependency><!--添加Swagger-UI依賴 -->
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.7.0</version>
           </dependency>
           <dependency> <!--添加熱部署依賴 -->
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-devtools</artifactId>
           </dependency>
           <dependency><!--添加Test依賴 -->
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-test</artifactId>
           <scope>test</scope>
           </dependency>
           </dependencies>

          2. 添加配置

          @Configuration //標記配置類
          @EnableSwagger2 //開啟在線接口文檔
          public class Swagger2Config {
           /**
           * 添加摘要信息(Docket)
           */
           @Bean
           public 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<User> 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<User>")
           @DeleteMapping("delete")
           public boolean delete(@RequestBody List<User> 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;
           }
          
           @Override
           public 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;
           }
          
           @Override
           public 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 版本對參數列表進行了改版,直接輸入參數,更方便進行測試操作:

          5. 測試接口

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

          以查詢用戶列表為例,無參數輸入,直接點擊“試一下”按鈕:

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

          好了,關于Swagger2在項目中的使用教程就到這里。


          主站蜘蛛池模板: 亚洲蜜芽在线精品一区| 国产一区二区精品| 色狠狠一区二区三区香蕉蜜桃| 国产成人无码一区二区三区在线 | 国产一区二区三区91| 人妻av综合天堂一区| 88国产精品视频一区二区三区| 国产精品无码不卡一区二区三区| 成人精品一区二区三区电影| 91一区二区三区四区五区| 中文字幕精品一区| 中文字幕一区二区三区精华液| 极品少妇一区二区三区四区| 在线中文字幕一区| 免费播放一区二区三区| 国偷自产Av一区二区三区吞精 | 一区二区日韩国产精品| 无码日韩精品一区二区免费| 亚洲狠狠狠一区二区三区| 麻豆高清免费国产一区| 精品无码一区二区三区爱欲| 国产精品女同一区二区| 麻豆精品久久久一区二区| 激情综合一区二区三区| 亚洲日韩精品一区二区三区无码| 韩国福利一区二区三区高清视频| 久久久久人妻精品一区三寸蜜桃| 亚洲av无码天堂一区二区三区 | 99久久国产精品免费一区二区| 果冻传媒一区二区天美传媒| 国产亚洲一区区二区在线 | 综合无码一区二区三区四区五区| 精品人妻系列无码一区二区三区| 人妻激情偷乱视频一区二区三区| 亚洲国产精品一区二区久| 国产小仙女视频一区二区三区| 日本一区二区三区不卡在线视频| 日本在线观看一区二区三区| 国产一区在线视频| 人体内射精一区二区三区| 亚洲丰满熟女一区二区哦|