轉載自?芋道 Spring Boot API 接口文檔 Swagger 入門

摘要: 原創出處 http://www.iocoder.cn/Spring-Boot/Swagger/ 「芋道源碼」歡迎轉載，保留摘要，謝謝！

本文在提供完整代碼示例，可見 https://github.com/YunaiV/SpringBoot-Labs 的 lab-24 目錄。

原創不易，給點個 Star 嘿，一起沖鴨！

1. 概述

目前，大多數系統都采用前后端分離。在享受前后端分離的好處的同時，接口聯調往往成為團隊效率的瓶頸，甚至產生前后端的矛盾。簡單歸結來說，有幾方面的原因：

• 問題一，接口設計滯后。?后端團隊往往不喜歡 API 接口設計先行，提前和前端溝通好接口。而在開發階段的中后期，在后端提供 API 接口后，而這些接口和前端的預期有一些偏差，很容易就產生抱怨，特別是項目周期比較緊張的情況下。

• 問題二，接口不規范。?當團隊里沒有同意明確的接口規范時，又或者代碼 Review 做的不是很好的情況下，千奇百怪、各式各樣的 API 接口可能就產生了。前端在對接這樣的 API 接口，苦不堪言，在一口 mmp 一嘴 fuck xxx 之中，調完接口。

• 問題三，接口文檔更新不及時，或者遺忘更新。?因為后端 API 代碼和 API 接口在兩個地方，我們無法保證提交 API 代碼的同時，及時更新文檔。有的時候，我們甚至會遺忘更新 API 接口。隨著時間的流逝，API 文檔和 API 接口不一致的地方越來越多，前端會對 API 接口的信任度越來越低，然后不知道不覺之中，回到原始時代，直接問后端開發 API 是什么樣的。

對于問題一和問題二，更多是開發流程上的問題，所以不在本文的范圍內。當然話癆的艿艿，還是要給點粗淺的建議，完全攔不住我啊。

• 接口設計先行。設計完成后，后端和前端進行簡單溝通，看看是否能夠滿足訴求。

• 統一的接口規范。一定要制定統一的接口規范文檔，即使比較簡陋，也能保證團隊的 API 接口相對統一一致。😈 即使錯，咱也錯的一模一樣，而不是千奇百怪。當然，接口規范是無法覆蓋到所有的場景的，借助于“接口設計先行”，我們可以提前去 Review 每個接口的設計。

對于問題三，就進入了本文的主角 Swagger?。通過在 API 接口上，添加相應的 Swagger 提供的注解，自動生成 API 文檔。醬紫，API 接口和文檔就在一起了，從此過上了幸福快樂的生活。

FROM 《RESTful 風格的 Web 服務框架 Swagger》

Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。

總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法、參數和模型緊密集成到服務器端的代碼，允許 API 來始終保持同步。Swagger 讓部署管理和使用功能強大的 API 從未如此簡單。

預覽圖

2. 快速入門 Swagger

示例代碼對應倉庫：lab-24-apidoc-swagger 。

在本小節，我們來快速入門 Swagger ，可以更加直觀的感受到其提供的便利性。

2.1 引入依賴

在?pom.xml?文件中，引入相關依賴。

<?xml?version="1.0"?encoding="UTF-8"?> <project?xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0?http://maven.apache.org/xsd/maven-4.0.0.xsd"><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/>?<!--?lookup?parent?from?repository?--></parent><modelVersion>4.0.0</modelVersion><artifactId>lab-24-apidoc-swagger</artifactId><dependencies><!--?實現對?Spring?MVC?的自動化配置?--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--?引入?Swagger?依賴?--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!--?引入?Swagger?UI?依賴，以實現?API?接口的?UI?界面?--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency></dependencies></project>

具體每個依賴的作用，胖友自己認真看下艿艿添加的所有注釋噢。

2.2 SwaggerConfiguration

因為 Spring Boot 暫未提供 Swagger 內置的支持，所以我們需要自己定義配置類。

在?cn.iocoder.springboot.lab24.apidoc.config?包路徑下，創建 SwaggerConfiguration 配置類，用于配置 Swagger 。代碼如下：

//?SwaggerConfiguration.java@Configuration @EnableSwagger2?//?標記項目啟用?Swagger?API?接口文檔 public?class?SwaggerConfiguration?{@Beanpublic?Docket?createRestApi()?{//?創建?Docket?對象return?new?Docket(DocumentationType.SWAGGER_2)?//?文檔類型，使用?Swagger2.apiInfo(this.apiInfo())?//?設置?API?信息//?掃描?Controller?包路徑，獲得?API?接口.select().apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.apidoc.controller")).paths(PathSelectors.any())//?構建出?Docket?對象.build();}/***?創建?API?信息*/private?ApiInfo?apiInfo()?{return?new?ApiInfoBuilder().title("測試接口文檔示例").description("我是一段描述").version("1.0.0")?//?版本號.contact(new?Contact("芋艿",?"http://www.iocoder.cn",?"zhijiantianya@gmail.com"))?//?聯系人.build();}}

• 在類上，添加?@EnableSwagger2?注解， 標記項目啟用 Swagger API 接口文檔。

• 通過?#createRestApi()?方法，創建 Swagger Docket Bean 。每個屬性的作用，胖友看看艿艿的注釋。大多數情況下，胖友使用這些屬性是足夠的。不過如果想看看其它配置，胖友可以自己去如下兩個類翻翻：

  • Docket.java

  • ApiInfo.java

2.3 Application

創建?Application.java?類，配置?@SpringBootApplication?注解即可。代碼如下：

//?Application.java@SpringBootApplication public?class?Application?{public?static?void?main(String[]?args)?{SpringApplication.run(Application.class,?args);}}

先暫時不啟動項目。等我們添加好 Controller 。

2.4 UserController

在?cn.iocoder.springboot.lab24.apidoc.controller?包路徑下，創建 UserController 類，提供用戶 API 接口。代碼如下：

//?UserController.java@RestController @RequestMapping("/users") @Api(tags?=?"用戶?API?接口") public?class?UserController?{@GetMapping("/list")@ApiOperation(value?=?"查詢用戶列表",?notes?=?"目前僅僅是作為測試，所以返回用戶全列表")public?List<UserVO>?list()?{//?查詢列表List<UserVO>?result?=?new?ArrayList<>();result.add(new?UserVO().setId(1).setUsername("yudaoyuanma"));result.add(new?UserVO().setId(2).setUsername("woshiyutou"));result.add(new?UserVO().setId(3).setUsername("chifanshuijiao"));//?返回列表return?result;}@GetMapping("/get")@ApiOperation("獲得指定用戶編號的用戶")@ApiImplicitParam(name?=?"id",?value?=?"用戶編號",?paramType?=?"query",?dataTypeClass?=?Integer.class,?required?=?true,?example?=?"1024")public?UserVO?get(@RequestParam("id")?Integer?id)?{//?查詢并返回用戶return?new?UserVO().setId(id).setUsername(UUID.randomUUID().toString());}@PostMapping("add")@ApiOperation("添加用戶")public?Integer?add(UserAddDTO?addDTO)?{//?插入用戶記錄，返回編號Integer?returnId?=?UUID.randomUUID().hashCode();//?返回用戶編號return?returnId;}@PostMapping("/update")@ApiOperation("更新指定用戶編號的用戶")public?Boolean?update(UserUpdateDTO?updateDTO)?{//?更新用戶記錄Boolean?success?=?true;//?返回更新是否成功return?success;}@PostMapping("/delete")@ApiOperation(value?=?"刪除指定用戶編號的用戶")@ApiImplicitParam(name?=?"id",?value?=?"用戶編號",?paramType?=?"query",?dataTypeClass?=?Integer.class,?required?=?true,?example?=?"1024")public?Boolean?delete(@RequestParam("id")?Integer?id)?{//?刪除用戶記錄Boolean?success?=?false;//?返回是否更新成功return?success;}}

• 相比我們之前使用 SpringMVC 來說，我們在類和接口上，額外增加了 Swagger 提供的注解。

• 從使用習慣上，我比較喜歡先添加 SpringMVC 的注解，再添加 Swagger 的注解。

• 因為已經使用了 Swagger 的注解，所以類和方法上的注釋，一般可以刪除了，除非有特殊訴求。

• 其中涉及到的 POJO 類，有 UserAddDTO、UserUpdateDTO、UserVO 。

執行 Application 啟動項目。然后瀏覽器訪問?http://127.0.0.1:8080/swagger-ui.html?地址，就可以看到 Swagger 生成的 API 接口文檔。如下圖所示：

至此，我們已經完成了 Swagger 的快速入門。不過考慮到胖友能夠更好的使用，我們來一個一個注解了解。

2.5 注解

在?swagger-annotations?庫中，在?io.swagger.annotations?包路徑下，提供了我們會使用到的所有 Swagger 注解。Swagger 提供的注解還是比較多的，大多數場景下，只需要使用到我們在 「2.4 UserController」 中用到的注解。

2.5.1 @Api

@Api?注解，添加在 Controller 類上，標記它作為 Swagger 文檔資源。

示例如下：

//?UserController.java@RestController @RequestMapping("/users") @Api(tags?=?"用戶?API?接口") public?class?UserController?{//?...?省略 }

效果如下：

@Api?注解的常用屬性，如下：

• tags?屬性：用于控制 API 所屬的標簽列表。[]?數組，可以填寫多個。

  • 可以在一個?Controller 上的?@Api?的?tags?屬性，設置多個標簽，那么這個 Controller 下的 API 接口，就會出現在這兩個標簽中。

  • 如果在多個?Controller 上的?@Api?的?tags?屬性，設置一個標簽，那么這些 Controller 下的 API 接口，僅會出現在這一個標簽中。

  • 本質上，tags?就是為了分組 API 接口，和 Controller 本質上是一個目的。所以絕大數場景下，我們只會給一個 Controller 一個唯一的標簽。例如說，UserController 的?tags?設置為?"用戶 API 接口"?。

@Api?注解的不常用屬性，如下：

• produces?屬性：請求請求頭的可接受類型( Accept )。如果有多個，使用?,?分隔。

• consumes?屬性：請求請求頭的提交內容類型( Content-Type )。如果有多個，使用?,?分隔。

• protocols?屬性：協議，可選值為?"http"、"https"、"ws"、"wss"?。如果有多個，使用?,?分隔。

• authorizations?屬性：授權相關的配置，[]?數組，使用?@Authorization?注解。

• hidden?屬性：是否隱藏，不再 API 接口文檔中顯示。

@Api?注解的廢棄屬性，不建議使用，有?value、description、basePath、position?。

2.5.2 @ApiOperation

@ApiOperation?注解，添加在 Controller 方法上，標記它是一個 API 操作。

示例如下：

//?UserController.java@GetMapping("/list") @ApiOperation(value?=?"查詢用戶列表",?notes?=?"目前僅僅是作為測試，所以返回用戶全列表") public?List<UserVO>?list()?{//?查詢列表List<UserVO>?result?=?new?ArrayList<>();result.add(new?UserVO().setId(1).setUsername("yudaoyuanma"));result.add(new?UserVO().setId(2).setUsername("woshiyutou"));result.add(new?UserVO().setId(3).setUsername("chifanshuijiao"));//?返回列表return?result; }

效果如下：

@ApiOperation?注解的常用屬性，如下：

• value?屬性：API 操作名。

• notes?屬性：API 操作的描述。

@ApiOperation?注解的不常用屬性，如下：

• tags?屬性：和?@API?注解的?tags?屬性一致。

• nickname?屬性：API 操作接口的唯一標識，主要用于和第三方工具做對接。

• httpMethod?屬性：請求方法，可選值為?GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH?。因為 Swagger 會解析 SpringMVC 的注解，所以一般無需填寫。

• produces?屬性：和?@API?注解的?produces?屬性一致。

• consumes?屬性：和?@API?注解的?consumes?屬性一致。

• protocols?屬性：和?@API?注解的?protocols?屬性一致。

• authorizations?屬性：和?@API?注解的?authorizations?屬性一致。

• hidden?屬性：和?@API?注解的?hidden?屬性一致。

• response?屬性：響應結果類型。因為 Swagger 會解析方法的返回類型，所以一般無需填寫。

• responseContainer?屬性：響應結果的容器，可選值為?List、Set、Map?。

• responseReference?屬性：指定對響應類型的引用。這個引用可以是本地，也可以是遠程。并且，當設置了它時，會覆蓋?response?屬性。說人話，就是可以忽略這個屬性，哈哈哈。

• responseHeaders?屬性：響應頭，[]?數組，使用?@ResponseHeader?注解。

• code?屬性：響應狀態碼，默認為 200 。

• extensions?屬性：拓展屬性，[]?屬性，使用?@Extension?注解。

• ignoreJsonView?屬性：在解析操作和類型，忽略 JsonView 注釋。主要是為了向后兼容。

@ApiOperation?注解的廢棄屬性，不建議使用，有?position?。

2.5.3 @ApiImplicitParam

@ApiImplicitParam?注解，添加在 Controller 方法上，聲明每個請求參數的信息。

示例如下：

//?UserController.java@PostMapping("/delete") @ApiOperation(value?=?"刪除指定用戶編號的用戶") @ApiImplicitParam(name?=?"id",?value?=?"用戶編號",?paramType?=?"query",?dataTypeClass?=?Integer.class,?required?=?true,?example?=?"1024") public?Boolean?delete(@RequestParam("id")?Integer?id)?{//?刪除用戶記錄Boolean?success?=?false;//?返回是否更新成功return?success; }

效果如下：

@ApiImplicitParam?注解的常用屬性，如下：

• name?屬性：參數名。

• value?屬性：參數的簡要說明。

• required?屬性：是否為必傳參數。默認為?false?。

• dataType?屬性：數據類型，通過字符串 String 定義。

• dataTypeClass?屬性：數據類型，通過?dataTypeClass?定義。在設置了?dataTypeClass?屬性的情況下，會覆蓋?dataType?屬性。推薦采用這個方式。

• paramType?屬性：參數所在位置的類型。有如下 5 種方式：

  • "path"?值：對應 SpringMVC 的?@PathVariable?注解。

  • 【默認值】"query"?值：對應 SpringMVC 的?@PathVariable?注解。

  • "body"?值：對應 SpringMVC 的?@RequestBody?注解。

  • "header"?值：對應 SpringMVC 的?@RequestHeader?注解。

  • "form"?值：Form 表單提交，對應 SpringMVC 的?@PathVariable?注解。

  • 😈?絕大多數情況下，使用?"query"?值這個類型即可。

• example?屬性：參數值的簡單示例。

• examples?屬性：參數值的復雜示例，使用?@Example?注解。

@ApiImplicitParam?注解的不常用屬性，如下：

• defaultValue?屬性：默認值。

• allowableValues?屬性：允許的值。如果要設置多個值，有兩種方式：

  • 數組方式，即?{value1, value2, value3}?。例如說，{1, 2, 3}?。

  • 范圍方式，即?[value1, value2]?或?[value1, value2)?。例如說?[1, 5]?表示 1 到 5 的所有數字。如果有無窮的，可以使用?(-infinity, value2]?或?[value1, infinity)?。

• allowEmptyValue?屬性：是否允許空值。

• allowMultiple?屬性：是否允許通過多次傳遞該參數來接受多個值。默認為?false?。

• type?屬性：搞不懂具體用途，對應英文注釋為?Adds the ability to override the detected type?。

• readOnly?屬性：是否只讀。

• format?屬性：自定義的格式化。

• collectionFormat?屬性：針對 Collection 集合的，自定義的格式化。

當我們需要添加在方法上添加多個?@ApiImplicitParam?注解時，可以使用 @ApiImplicitParams 注解中添加多個。示例如下：

@ApiImplicitParams({?//?參數數組@ApiImplicitParam(name?=?"id",?value?=?"用戶編號",?paramType?=?"query",?dataTypeClass?=?Integer.class,?required?=?true,?example?=?"1024"),?//?參數一@ApiImplicitParam(name?=?"name",?value?=?"昵稱",?paramType?=?"query",?dataTypeClass?=?String.class,?required?=?true,?example?=?"芋道"),?//?參數二 })

2.5.4 @ApiModel

@ApiModel?注解，添加在 POJO 類，聲明 POJO 類的信息。而在 Swagger 中，把這種 POJO 類稱為?Model?類。所以，我們下文就統一這么稱呼。

示例如下：

//?UserVO.java@ApiModel("用戶?VO") public?class?UserVO?{//?...?省略}

效果如下：

@ApiModel?注解的常用屬性，如下：

• value?屬性：Model 名字。

• description?屬性：Model 描述。

@ApiModel?注解的不常用屬性，如下：

• parent?屬性：指定該 Model 的父 Class 類，用于繼承父 Class 的 Swagger 信息。

• subTypes?屬性：定義該 Model 類的子類 Class 們。

• discriminator?屬性：搞不懂具體用途，對應英文注釋為?Supports model inheritance and polymorphism.

• reference?屬性：搞不懂具體用途，對應英文注釋為?Specifies a reference to the corresponding type definition, overrides any other metadata specified

2.5.5 @ApiModelProperty

@ApiModelProperty?注解，添加在 Model 類的成員變量上，聲明每個成員變量的信息。

示例如下：

//?UserVO.java@ApiModel("用戶?VO") public?class?UserVO?{@ApiModelProperty(value?=?"用戶編號",?required?=?true,?example?=?"1024")private?Integer?id;@ApiModelProperty(value?=?"賬號",?required?=?true,?example?=?"yudaoyuanma")private?String?username;//?...?省略?set/get?方法 }

效果如下：

@ApiModelProperty?注解的常用屬性，如下：

• value?屬性：屬性的描述。

• dataType?屬性：和?@ApiImplicitParam?注解的?dataType?屬性一致。不過因為?@ApiModelProperty?是添加在成員變量上，可以自動獲得成員變量的類型。

• required?屬性：和?@ApiImplicitParam?注解的?required?屬性一致。

• example?屬性：@ApiImplicitParam?注解的?example?屬性一致。

@ApiModelProperty?注解的不常用屬性，如下：

• name?屬性：覆蓋成員變量的名字，使用該屬性進行自定義。

• allowableValues?屬性：和?@ApiImplicitParam?注解的?allowableValues?屬性一致。

• position?屬性：成員變量排序位置，默認為 0 。

• hidden?屬性：@ApiImplicitParam?注解的?hidden?屬性一致。

• accessMode?屬性：訪問模式，有?AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE?三種，默認為?AccessMode.AUTO?。

• reference?屬性：和?@ApiModel?注解的?reference?屬性一致。

• allowEmptyValue?屬性：和?@ApiImplicitParam?注解的?allowEmptyValue?屬性一致。

• extensions?屬性：和?@ApiImplicitParam?注解的?extensions?屬性一致。

@ApiModelProperty?注解的廢棄屬性，不建議使用，有?readOnly?。

2.5.6 @ApiResponse

在大多數情況下，我們并不需要使用?@ApiResponse?注解，因為我們會類似?UserController#get(id)?方法這個接口，返回一個 Model 即可。所以?@ApiResponse?注解，艿艿就簡單講解，嘿嘿。

@ApiResponse?注解，添加在 Controller 類的方法上，聲明每個響應參數的信息。

@ApiResponse?注解的屬性，基本已經被?@ApiOperation?注解所覆蓋，如下：

• message?屬性：響應的提示內容。

• code?屬性：和?@ApiOperation?注解的?code?屬性一致。

• response?屬性：和?@ApiOperation?注解的?response?屬性一致。

• reference?屬性：和?@ApiOperation?注解的?responseReference?屬性一致。

• responseHeaders?屬性：和?@ApiOperation?注解的?responseHeaders?屬性一致。

• responseContainer?屬性：和?@ApiOperation?注解的?responseContainer?屬性一致。

• examples?屬性：和?@ApiOperation?注解的?examples?屬性一致。

當我們需要添加在方法上添加多個?@ApiResponse?注解時，可以使用 @ApiResponses 注解中添加多個。

至此，我們已經了解完 Swagger 項目中提供的主要注解。如果想要看到更多的 Swagger 的使用示例，可以看看艿艿開源的 onemall 項目。

咳咳咳，整理 Swagger 注解的每個屬性，真的是花費時間。如果有哪個解釋不到位，請一定給艿艿留言，我去優化和調整下，嘻嘻。

2.6 測試接口

在 Swagger 的 UI 界面上，提供了簡單的測試接口的工具。我們僅僅需要點開某個接口，點擊「Try it out」按鈕。如下圖：

然后，點擊「Execute」按鈕，即可執行一次 API 接口的調用。如下圖：

在三個紅圈中，我們可以看到 Swagger 給我們提供了：

• 提供了 curl 命令，讓我們可以直接在命令行執行。

• 提供了 Request URL 地址，方便我們在瀏覽器中訪問。

• 提供了執行結果，我們可以人肉看看，是否符合我們希望的結果。

😈 當然，實際項目開發中，艿艿還是喜歡 Postman 來測試接口，嘿嘿。

3. 更好看的 Swagger UI 界面

示例代碼對應倉庫：lab-24-apidoc-swagger-knife4j 。

springfox-swagger-ui?提供的 UI 界面，基本能夠滿足我們的日常使用，但是距離好用，還是有一段距離。幸福的是，社區有人開源了?swagger-bootstrap-ui?項目，提供更好看且好用的 UI 界面。

具體的演示示例，可以訪問：http://swagger-bootstrap-ui.xiaominfo.com/doc.html 查看。

在 「2. 快速入門 Swagger」 的?lab-24-apidoc-swagger?示例的基礎上，我們復制出?lab-24-apidoc-swagger-knife4j?項目，進行改造。

3.1 修改依賴

在?pom.xml?文件中，修改相關依賴。

<?xml?version="1.0"?encoding="UTF-8"?> <project?xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0?http://maven.apache.org/xsd/maven-4.0.0.xsd"><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/>?<!--?lookup?parent?from?repository?--></parent><modelVersion>4.0.0</modelVersion><artifactId>lab-24-apidoc-swagger-knife4j</artifactId><dependencies><!--?實現對?Spring?MVC?的自動化配置?--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--?1.?swagger-bootstrap-ui?目前改名為?knife4j?--><!--?2.?實現?swagger-bootstrap-ui?的自動化配置??--><!--?3.?因為?knife4j-spring?已經引入?Swagger?依賴，所以無需重復引入?--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring</artifactId><version>1.9.6</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-ui</artifactId><version>1.9.6</version></dependency></dependencies></project>

具體每個依賴的作用，胖友自己認真看下艿艿添加的所有注釋噢。

3.2 界面一覽

直接使用 Application 啟動項目，無需做其它任何的變更，方便的說。

瀏覽器訪問?http://localhost:8080/doc.html?地址，就可以看到?新的 Swagger 生成的 API 接口文檔。

😈 注意下，界面上艿艿添加的紅圈和紅字噢。更多功能，胖友自己看 官方文檔 喲。非常推薦生產中，使用它，嘿嘿。

4. 更強大的 YApi

雖然說 Swagger 已經挺強大了，可以很好的完成提供后端 API 接口文檔的功能，但是實際場景下，我們還是會碰到很多問題：

• Swagger 沒有內置 Mock 功能。在實際的開發中，在后端定義好 API 接口之后，前端會根據 API 接口，進行接口的 Mock ，從而實現前后端的并行開發。

• 多個項目的 API 接口文檔的整合。隨著微服務的流行，一個產品實際是拆分成多個微服務項目，提供 API 接口。那么，一個微服務項目，一個接口文檔，肯定會氣死前端。氣死一個前端小哥哥沒事，如果是小姐姐那多可惜啊。

所以，我們需要更加強大的 API 接口管理平臺。目前艿艿團隊采用的解決方案是：

• 后端開發，還是使用 Swagger 注解，生成 API 接口文檔。

• 使用 YApi 可視化接口管理平臺，自動調用 Swagger 提供的?v2/api-docs?接口，采集 Swagger 注解生成的 API 接口信息，從而錄入到 YApi 中。

這樣，我們既可以享受到 Swagger 帶給我們編寫 API 接口文檔的便利性與及時性，又能享受到 YApi 的強大功能。

FROM https://github.com/YMFE/yapi

YApi 是高效、易用、功能強大的 api 管理平臺，旨在為開發、產品、測試人員提供更優雅的接口管理服務。可以幫助開發者輕松創建、發布、維護 API，YApi 還為用戶提供了優秀的交互體驗，開發人員只需利用平臺提供的接口數據寫入工具以及簡單的點擊操作就可以實現接口的管理。

• 基于 Json5 和 Mockjs 定義接口返回數據的結構和文檔，效率提升多倍

• 扁平化權限設計，即保證了大型企業級項目的管理，又保證了易用性

• 類似 postman 的接口調試

• 自動化測試, 支持對 Response 斷言

• MockServer 除支持普通的隨機 mock 外，還增加了 Mock 期望功能，根據設置的請求過濾規則，返回期望數據

• 支持 postman, har, swagger 數據導入

• 免費開源，內網部署，信息再也不怕泄露了

胖友可以訪問 http://yapi.demo.qunar.com/ 地址，快速體驗下 Yapi 的功能。

下面，我們就一起來搭建一個 YApi 平臺，美滋滋。因為 YApi 基于 NodeJS 語言開發，使用 MongoDB 作為數據庫存儲接口信息，所以我們需要先安裝 NodeJS 和 MongoDB 。

艿艿：目前手頭上只有 MacOS 和 CentOS 環境，所以如下的步驟，暫支也只保證這兩個環境，抱歉~

如果使用 Windows 或者 Ubuntu 的同學，請辛苦自行解決下。

4.1 安裝 MongoDB

參考 《芋道 MongoDB 極簡入門》 文章，先進行下安裝 MongoDB 數據庫。

安裝完成，記得參考文章，創建一個?yapi?數據庫，后續我們會使用到。

4.2 安裝 NodeJS

如果胖友是 CentOS 環境，使用?yum install nodejs?命令，進行安裝。

如果胖友是 MacOS 環境，使用?brew install node?命令，進行安裝。如果沒有 brew 的胖友，這么 666 的神器，不趕緊安裝下嘛？！

4.3 安裝 yapi-cli

使用我們提供的 yapi-cli 工具，部署 YApi 平臺是非常容易的。執行 yapi server 啟動可視化部署程序，輸入相應的配置和點擊開始部署，就能完成整個網站的部署。部署完成之后，可按照提示信息，執行 node/{網站路徑/server/app.js} 啟動服務器。在瀏覽器打開指定 url, 點擊登錄輸入您剛才設置的管理員郵箱，默認密碼為 ymfe.org 登錄系統（默認密碼可在個人中心修改）。

#?安裝?yapi-cli?工具 $?npm?install?-g?yapi-cli?--registry?https://registry.npm.taobao.org#?啟動?YApi?平臺部署工具 $?yapi?server 在瀏覽器打開?http://0.0.0.0:9090?訪問。非本地服務器，請將?0.0.0.0?替換成指定的域名或ip

4.4 YApi 平臺部署

在瀏覽器打開?http://127.0.0.1:9090?地址，設置 YApi 平臺部署的信息。如下圖：

點擊「開始部署」按鈕，會彈出“部署日志”窗口。如下圖：

耐心等待，直到出現日志如下：

初始化管理員賬號成功,賬號名："zhijiantianya@gmail.com"，密碼："ymfe.org" 部署成功，請切換到部署目錄，輸入：?"node?vendors/server/app.js"?指令啟動服務器,?然后在瀏覽器打開?http://127.0.0.1:3000?訪問

此時，我們可以在命令行執行 ctrl-c 操作，關閉YApi 平臺部署工具。

4.5 YApi 平臺啟動

在命令行中，執行如下命令，啟動 YApi 平臺。

#?進入?yapi?部署路徑 $?cd?/Users/yunai/my-yapi/#?啟動?yapi?平臺 $?node?vendors/server/app.js log:?-------------------------------------swaggerSyncUtils?constructor----------------------------------------------- log:?服務已啟動，請打開下面鏈接訪問: http://127.0.0.1:3000/ log:?mongodb?load?success...

項目啟動完成。如果真正開始使用時，建議使用 pm2 方便服務管理維護。命令如下：

npm?install?pm2?-g??//?安裝pm2 cd??{項目目錄} pm2?start?"vendors/server/app.js"?--name?yapi?//?pm2管理yapi服務 pm2?info?yapi?//?查看服務信息 pm2?stop?yapi?//?停止服務 pm2?restart?yapi?//?重啟服務

這里，我們可以先略過這個操作，繼續往下看。畢竟，咱現在的重心是先入門。

4.5 創建項目

瀏覽器打開?http://127.0.0.1:3000/?地址，輸入賬號密碼登陸。

• 登陸賬號，就是管理員郵箱。例如說，艿艿這里使用的是 zhijiantianya@gmail.com

• 登陸密碼，默認使用 ymfe.org 。

登陸成功后，自動跳轉到主界面，點擊右邊的「添加項目」按鈕，進入「新建項目」的界面(http://127.0.0.1:3000/add-project) 。如下圖：

點擊下方的「創建項目」按鈕，完成項目的創建。創建成功后，我們會自動動跳轉到剛才創建的項目下。如下圖：

4.6 設置 Swagger 自動同步

點擊「設置」欄目，然后選擇「Swagger自動同步」欄目，設置 Swagger 自動同步信息。如下圖：

友情提示：Swagger 默認會自動暴露?項目地址/v2/api-docs?接口，提供 Swagger 根據注解自動生成的 API 接口信息。胖友可以手動請求下該接口，感受下。

實際上，無論是 Swagger UI 也是基于該接口，獲得 API 接口信息。

點擊「保存」按鈕。成功后，點擊「接口」欄目，就可以看到自動同步到的接口信息。如下圖：

至此，我們已經完成搭建 YApi 平臺，并自動采集 Swagger 提供的 API 接口信息。YApi 的功能非常強大，一定要翻一翻 官方文檔 喲。例如說，數據 Mock、高級 Mock 、自動化測試等等功能，都是非常值得在項目中實踐使用。

666. 彩蛋

那么，在有了 API 接口文檔之后，如何和前端更好的溝通呢？

一般來說，每一個版本的需求，產品都會提供 Axure 文檔。后端開發在設計完接口之后，可以考慮在每個界面上，標記上使用到的接口的文檔地址。注意，是接口的文檔地址啊！！！例如說，登陸界面需要使用到登陸接口，那么我們可以把登陸接口對應的文檔地址 http://127.0.0.1:3000/project/14/interface/api/11 標記到這個界面的原型上。

當然，做標記的原則是，需要跟產品協商好可以用來標記的區域，不能影響到他們的工作。例如說：

友情提示：Axure 也是支持 團隊協作 的噢。如果胖友家的產品還沒使用，批評（怒噴）一下他們。

這樣，在原型上標記好接口之后，我們就可以找前端妹子，對著原型，順著接口走一遍流程。如果走的很順暢，說明咱的接口棒棒的。嘿嘿~

一定要記住，工具僅僅是工具，一定要盡早達成前后端的一致。

---

下面，進入話癆艿艿的碎碎念環節，分享下艿艿在 API 接口文檔的心路歷程。

艿艿最早是在 2010 年的時候，接觸到前后端分離的架構。當時前端使用 ActionScript ，后端使用 Servlet + JDBC ，通過 JSON 數據格式做交互，開發一款 QQ 農場的網頁游戲。😈 嘿嘿，不要嫌棄 Servlet + JDBC 很搓，當時才學 Java 3 個月左右。那時候吧，一個前端 + 兩個后端，人少，直接 QQ 上發 API 接口的定義。是不是非常遠古時代的做法，嘻嘻。

在 2011 年的時候，開始第一份工作的實習。公司管理后臺前端采用的是 ExtJS ，后端使用 SpringMVC 提供接口。架構還是采用前后端分離，不過前端 JS 代碼還是后端開發來編寫，所以也就不存在 API 接口文檔一說了。這個時候，更多的是自我約束，強制自己先設計好 API 接口，然后順著產品原型走一圈。如果沒問題，就開始編寫后端 API 接口的實現。完成之后，在編寫前端 JS 代碼~

在 2013 年的時候，開始了又一次創業的遨游。項目的前端是 iOS 和 Android 客戶端，順理成章的還是前后端分離。因為客戶端分成 iOS 和 Android 客戶端版本，并且還是兩個不同的開發小哥（是的，竟然沒一個是小姐姐），所以艿艿只好提供 API 接口的文檔。這個時候的 API 接口的文檔方案比較土，土豆的土，使用的是 Word 文檔 + SVN 協作。可想而知，大幾十頁的，一點打開的欲望都沒有。😈 更痛苦的是，Word 文檔的內容，是不支持 SVN 比對合并的，這就導致未來的一段時間，我們發展到 10+ 后端開發的時候，瘋狂的沖突。

在 2015 年的時候，差不多是這個點吧，記憶有點模糊了。我們開始使用 Confluence 作為我們的 Wiki 工具，新的 API 接口文檔自然就被調整到在上面編寫，而老的 API 接口慢慢遷移上來。帶來的好處不言而喻，終于解決多人協作老沖突的問題。同時，Confluence 支持 Template 模板，也比較容易的控制 API 接口的格式和規范。當然，比較大的困擾，還是文頭提到的問題三，經常有同學忘記更新 API 文檔，導致代碼和文檔越來越不一致。

在 2016 年的時候，愛倒騰的艿艿，無意中發現網易提供的 NEI 接口管理平臺。當時從 Confluence 替換成 NEI 的原因，有點不太記得，好像是 NEI 更加結構化，也更加專業。畢竟，Confluence 是一個 Wiki 工具，而不是專為 API 接口設計的管理平臺。當然，此時問題三還是存在的。

在 2019 年的時候，剛好開始了一個新項目，抱著比較嘗試的心態，使用了 Swagger 來編寫接口文檔，效果其好，主要也是解決了問題三。更舒服的是，相比 NEI 上編寫接口文檔，😈 可以復制粘貼代碼，效率也提升了蠻多。

再后來，我們引入了 YApi 接口管理平臺，形成了我們 Swagger + YApi + Axure 標記的整體方案。大體就是醬紫。深夜 02:16 了，結束今天的嗶嗶，迎接明天的嗶嗶。

總結

以上是生活随笔為你收集整理的Spring Boot API 接口文档 Swagger 入门的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。