上传API至API网关

前提条件

• 已在IntelliJ IDEA中安装和配置Cloud Toolkit，且版本在2023.10.1及以上。具体操作，请参见在IntelliJ IDEA中安装和配置Cloud Toolkit。

• 已在API网关中创建API分组。具体操作，请参见创建分组。

准备工作

您可直接使用已有项目测试API上传功能，也可使用本文提供的示例工程：Demo。

步骤一：配置API网关插件

1. 在IntelliJ IDEA顶部菜单栏，选择File > Settings。

2. 在Settings页面左侧导航栏，选择Alibaba Cloud Toolkit > Microservice > API Gateway。

   

   配置参数说明如下：

   配置项	描述
   区域	网关实例所在的地域。
   API分组	分组是API的管理单元。创建API之前，需先创建API分组，解析后的API将归属于选中的分组。 重要 目标API分组的BasePath需与OAS定义中的BasePath保持一致，否则将无法导入。
   API定义版本	OAS版本信息。当前仅支持OAS2.0的导入方式。
   后端服务	默认后端类型为Mock类型。
   是否覆盖	是否覆盖现有API。HTTP请求类型以及后端请求路径相同时，覆盖现有API。
   忽略警告信息	是否忽略警告信息。
   API认证方式	API安全认证类型： APP：只允许已授权的App调用。 ANONYMOUS：允许匿名调用。 重要 设置为允许匿名调用时，任何能够获取该API服务信息的人，都能调用该API。网关不会对调用者做身份认证，也无法设置流量控制。若开放该API，请设置好API的流量控制。
   入参请求模式	默认的方式为参数透传，可以选择参数透传、参数映射以及透传映射。 MAPPING：入参映射（过滤未知参数）。 PASSTHROUGH：入参透传。 MAPPING_PASSTHROUGH：映射透传（透传未知参数）。 说明 如果入参请求模式为透传模式，API定义中的参数定义只会录入path参数，query、header、formdata和body等参数将会被忽略。

步骤二：上传API至API网关

1. 在Controller/RestController控制器类所在的文件中，右键选择Alibaba Cloud > Upload to API Gateway，可自动解析出当前文件的所有接口，触发一次上传预检。

   

2. 在预检结果对话框，确认解析接口无误后，单击导入将接口上传至API网关。

   

3. 导入完成后，可以在API网关控制台的开放API > API列表页面确认导入的结果。

   

步骤三：测试上传

本文示例Demo配置了Swagger，您可以访问http://localhost:8080/v2/api-docs查看实际的OAS定义，并与API网关插件生成的API定义进行对比。API网关插件不依赖Swagger，您可在安装插件后直接上传API，无需启动工程。

Spring支持说明

Spring注解的使用相对自由，体现了服务端对于请求的处理能力。例如，@RequestMapping注解在不指定Method时，代表处理任意请求方法。而在OAS规范中，一个API的请求方法、请求路径以及请求参数是确定的，API定义明确，表达了希望客户端调用的方式。API网关插件针对这两个语义进行了约定，以下是一些参考示例。

• 参数缺省注解会被认为是@RequestParam，并解析为in=query。示例：

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

  入参isbn被解析为in=query。

• 如果@RequestMapping注解未指定具体请求方法，插件将会生成GET和POST两个API。示例：

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

• 如果方法包含@PostMapping注解，入参将被解析为in=formdata，示例：

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

  入参isbn和title被解析为in=formdata。

• 如果方法包含@PostMapping注解，且方法参数包含@RequestBody注解，参数未指定consumes时，推测consumes=application/json。示例：

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

  入参book会被解析为in=body。

其他约定与您使用Spring时的认知基本保持一致。尽管插件做了很多推测，但仍应使用明确的声明定义API。

• 声明精确的请求方法，使用@PostMapping和@GetMapping，而不是@RequestMapping。

• 使用@PostMapping时，需声明精确的consumes。consumes对应HTTP请求的Content-Type，Content-Type中常见的类型有表单参数类型application/x-www-form-urlencoded、form-data和JSON数据类型application/json。API网关插件在处理表单类型和JSON数据类型时，解析格式完全不同。

• 使用@RequestParam、@RequestHeader等参数注解时，可通过name属性指定字段名，required属性指定是否必填。该信息都会体现在API定义中。

解析支持说明

• 以下常见的包装类在解析时会去除包装，针对内容进行字段解析。当前不支持自定义需要拆包的包装类型。

  • 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

• 针对内置的变量，例如HttpServletRequest, HttpServletResponse和HttpSession等，将会忽略解析。当前不支持自定义忽略解析的参数类型。

• 支持泛型对象，例如BaseResult<Book>。当参数包含泛型时，建议明确指明，请勿配置为BaseResult，否则不会对Book类型进行解析。

• 支持枚举类型。

• 支持集合对象Collection、Map。

• 支持请求和响应对象循环引用。

• 支持注解的属性配置的优先级高于缺省配置。例如，RequestParam(name="id") String bookId优先使用id作为API字段名。缺省情况下，使用bookId该字面量作为API字段名。