前提條件

• 已在IntelliJ IDEA中安裝和配置Cloud Toolkit，且版本在2023.10.1及以上。具體操作，請(qǐng)參見(jiàn)在IntelliJ IDEA中安裝和配置Cloud Toolkit。

• 已在API網(wǎng)關(guān)中創(chuàng)建API分組。具體操作，請(qǐng)參見(jiàn)創(chuàng)建分組。

準(zhǔn)備工作

您可直接使用已有項(xiàng)目測(cè)試API上傳功能，也可使用本文提供的示例工程：Demo。

步驟一：配置API網(wǎng)關(guān)插件

1. 在IntelliJ IDEA頂部菜單欄，選擇File > Settings。

2. 在Settings頁(yè)面左側(cè)導(dǎo)航欄，選擇Alibaba Cloud Toolkit > Microservice > API Gateway。

   

   配置參數(shù)說(shuō)明如下：

   配置項(xiàng)	描述
   區(qū)域	網(wǎng)關(guān)實(shí)例所在的地域。
   API分組	分組是API的管理單元。創(chuàng)建API之前，需先創(chuàng)建API分組，解析后的API將歸屬于選中的分組。 重要 目標(biāo)API分組的BasePath需與OAS定義中的BasePath保持一致，否則將無(wú)法導(dǎo)入。
   API定義版本	OAS版本信息。當(dāng)前僅支持OAS2.0的導(dǎo)入方式。
   后端服務(wù)	默認(rèn)后端類型為Mock類型。
   是否覆蓋	是否覆蓋現(xiàn)有API。HTTP請(qǐng)求類型以及后端請(qǐng)求路徑相同時(shí)，覆蓋現(xiàn)有API。
   忽略警告信息	是否忽略警告信息。
   API認(rèn)證方式	API安全認(rèn)證類型： APP：只允許已授權(quán)的App調(diào)用。 ANONYMOUS：允許匿名調(diào)用。 重要 設(shè)置為允許匿名調(diào)用時(shí)，任何能夠獲取該API服務(wù)信息的人，都能調(diào)用該API。網(wǎng)關(guān)不會(huì)對(duì)調(diào)用者做身份認(rèn)證，也無(wú)法設(shè)置流量控制。若開(kāi)放該API，請(qǐng)?jiān)O(shè)置好API的流量控制。
   入?yún)⒄?qǐng)求模式	默認(rèn)的方式為參數(shù)透?jìng)鳎梢赃x擇參數(shù)透?jìng)鳌?shù)映射以及透?jìng)饔成洹?/p> MAPPING：入?yún)⒂成洌ㄟ^(guò)濾未知參數(shù)）。 PASSTHROUGH：入?yún)⑼競(jìng)鳌?/p> MAPPING_PASSTHROUGH：映射透?jìng)鳎ㄍ競(jìng)魑粗獏?shù)）。 說(shuō)明 如果入?yún)⒄?qǐng)求模式為透?jìng)髂Ｊ剑珹PI定義中的參數(shù)定義只會(huì)錄入path參數(shù)，query、header、formdata和body等參數(shù)將會(huì)被忽略。

步驟二：上傳API至API網(wǎng)關(guān)

1. 在Controller/RestController控制器類所在的文件中，右鍵選擇Alibaba Cloud > Upload to API Gateway，可自動(dòng)解析出當(dāng)前文件的所有接口，觸發(fā)一次上傳預(yù)檢。

   

2. 在預(yù)檢結(jié)果對(duì)話框，確認(rèn)解析接口無(wú)誤后，單擊導(dǎo)入將接口上傳至API網(wǎng)關(guān)。

   

3. 導(dǎo)入完成后，可以在API網(wǎng)關(guān)控制臺(tái)的開(kāi)放API > API列表頁(yè)面確認(rèn)導(dǎo)入的結(jié)果。

   

步驟三：測(cè)試上傳

本文示例Demo配置了Swagger，您可以訪問(wèn)http://localhost:8080/v2/api-docs查看實(shí)際的OAS定義，并與API網(wǎng)關(guān)插件生成的API定義進(jìn)行對(duì)比。API網(wǎng)關(guān)插件不依賴Swagger，您可在安裝插件后直接上傳API，無(wú)需啟動(dòng)工程。

Spring支持說(shuō)明

Spring注解的使用相對(duì)自由，體現(xiàn)了服務(wù)端對(duì)于請(qǐng)求的處理能力。例如，@RequestMapping注解在不指定Method時(shí)，代表處理任意請(qǐng)求方法。而在OAS規(guī)范中，一個(gè)API的請(qǐng)求方法、請(qǐng)求路徑以及請(qǐng)求參數(shù)是確定的，API定義明確，表達(dá)了希望客戶端調(diào)用的方式。API網(wǎng)關(guān)插件針對(duì)這兩個(gè)語(yǔ)義進(jìn)行了約定，以下是一些參考示例。

• 參數(shù)缺省注解會(huì)被認(rèn)為是@RequestParam，并解析為in=query。示例：

  @GetMapping(value = "/getBook")
  public BaseResult<Book> getBook(String isbn) {
      return BaseResult.ok(new Book());
  }

  入?yún)?code data-tag="code" class="code">isbn被解析為in=query。

• 如果@RequestMapping注解未指定具體請(qǐng)求方法，插件將會(huì)生成GET和POST兩個(gè)API。示例：

  @RequestMapping(value = "/getBook")
  public BaseResult<Book> getBook(String isbn) {
      return BaseResult.ok(new Book());
  }

• 如果方法包含@PostMapping注解，入?yún)⒈唤馕鰹?code data-tag="code" class="code">in=formdata，示例：

  @PostMapping(value = "/createBook")
  public BaseResult<Book> createBook(String isbn, String title) {
      return BaseResult.ok(new Book());
  }

  入?yún)?code data-tag="code" class="code">isbn和title被解析為in=formdata。

• 如果方法包含@PostMapping注解，且方法參數(shù)包含@RequestBody注解，參數(shù)未指定consumes時(shí)，推測(cè)consumes=application/json。示例：

  @PostMapping(value = "/createBook")
  public BaseResult<Book> createBook(@RequestBody Book book) {
      return BaseResult.ok(book);
  }

  入?yún)?code data-tag="code" class="code">book會(huì)被解析為in=body。

其他約定與您使用Spring時(shí)的認(rèn)知基本保持一致。盡管插件做了很多推測(cè)，但仍應(yīng)使用明確的聲明定義API。

• 聲明精確的請(qǐng)求方法，使用@PostMapping和@GetMapping，而不是@RequestMapping。

• 使用@PostMapping時(shí)，需聲明精確的consumes。consumes對(duì)應(yīng)HTTP請(qǐng)求的Content-Type，Content-Type中常見(jiàn)的類型有表單參數(shù)類型application/x-www-form-urlencoded、form-data和JSON數(shù)據(jù)類型application/json。API網(wǎng)關(guān)插件在處理表單類型和JSON數(shù)據(jù)類型時(shí)，解析格式完全不同。

• 使用@RequestParam、@RequestHeader等參數(shù)注解時(shí)，可通過(guò)name屬性指定字段名，required屬性指定是否必填。該信息都會(huì)體現(xiàn)在API定義中。

解析支持說(shuō)明

• 以下常見(jiàn)的包裝類在解析時(shí)會(huì)去除包裝，針對(duì)內(nèi)容進(jìn)行字段解析。當(dāng)前不支持自定義需要拆包的包裝類型。

  • org.springframework.http.ResponseEntity

  • reactor.core.publisher.Flux

  • reactor.core.publisher.Mono

  • java.util.concurrent.Callable

  • org.springframework.web.context.request.async.DeferredResult

  • org.springframework.web.context.request.async.WebAsyncTask

  • java.util.concurrent.Future

  • java.util.concurrent.CompletableFuture

• 針對(duì)內(nèi)置的變量，例如HttpServletRequest, HttpServletResponse和HttpSession等，將會(huì)忽略解析。當(dāng)前不支持自定義忽略解析的參數(shù)類型。

• 支持泛型對(duì)象，例如BaseResult<Book>。當(dāng)參數(shù)包含泛型時(shí)，建議明確指明，請(qǐng)勿配置為BaseResult，否則不會(huì)對(duì)Book類型進(jìn)行解析。

• 支持枚舉類型。

• 支持集合對(duì)象Collection、Map。

• 支持請(qǐng)求和響應(yīng)對(duì)象循環(huán)引用。

• 支持注解的屬性配置的優(yōu)先級(jí)高于缺省配置。例如，RequestParam(name="id") String bookId優(yōu)先使用id作為API字段名。缺省情況下，使用bookId該字面量作為API字段名。