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 項目的集成已表現出良好的適應性，Springfox和Springdoc作為領先的開源庫促進了這一整合。

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

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

在線咨詢

上一篇：作為動詞的shanghai：美國加州的一段黑歷史
下一篇：CSS圖片瀏覽效果

您的項目需求

*請認真填寫需求信息，我們會在24小時內與您取得聯系。

整合營銷服務商