文档

上传API至API网关

更新时间:
一键部署

使用Cloud Toolkit可以解析Spring项目,将Controller/RestController中的接口自动解析为API上传至API网关。您无需手动录入API,便可快速完成API网关的接口信息录入。本文介绍如何将API上传至API网关。

前提条件

准备工作

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

步骤一:配置API网关插件

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

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

    image.png

    配置参数说明如下:

    配置项

    描述

    区域

    网关实例所在的地域。

    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,可自动解析出当前文件的所有接口,触发一次上传预检。

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

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

    image.png

步骤三:测试上传

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

Spring支持说明

说明

API网关插件通过扫描工程中的Spring注解实现接口解析,无需添加Swagger相关依赖。

  • 扫描的类必须包含@RestController@Controller注解。

  • 扫描的方法必须包含@RequestMapping@GetMapping@PostMapping@DeleteMapping@PutMapping@PacthMapping注解之一。

  • 扫描的参数支持@RequestParam@RequestBody@PathVariable@RequestHeader注解,并支持推测缺省参数注解。

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());
    }

    入参isbntitle被解析为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-urlencodedform-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, HttpServletResponseHttpSession等,将会忽略解析。当前不支持自定义忽略解析的参数类型。

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

  • 支持枚举类型。

  • 支持集合对象Collection、Map。

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

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

  • 本页导读 (0)