Upload APIs to API Gateway

Prerequisites

• You have installed and configured Cloud Toolkit in IntelliJ IDEA. The version must be 2023.10.1 or later. For more information, see Install and configure Cloud Toolkit in IntelliJ IDEA.

• You have created an API group in API Gateway. For more information, see Create an API group.

Preparations

You can test the API upload feature using an existing project or the sample project provided in this topic: Demo.

Step 1: Configure the API Gateway plugin

1. In the IntelliJ IDEA menu bar, select File > Settings.

2. In the navigation pane on the left of the Settings page, select Alibaba Cloud Toolkit > Microservice > API Gateway.

   The following table describes the parameters.

   Configuration	Description
   Region	The region where the gateway instance is located.
   API group	An API group is a management unit for APIs. Before you create an API, you must create an API group. The parsed APIs will belong to the selected group. Important The BasePath of the destination API group must be the same as the BasePath in the OpenAPI Specification (OAS) definition. Otherwise, the import will fail.
   API definition version	The OAS version. Only OAS 2.0 is supported for import.
   Backend service	The default backend service type is Mock.
   Overwrite	Specifies whether to overwrite existing APIs. If the HTTP request type and the backend request path are the same, the existing API is overwritten.
   Ignore warnings	Specifies whether to ignore warnings.
   API authentication method	The API security authentication type: APP: Only authorized apps can call the API. ANONYMOUS: Anonymous calls are allowed. Important If you allow anonymous calls, anyone who obtains the API service information can call the API. The gateway does not authenticate callers and cannot apply throttling. If you make this API public, configure throttling for the API.
   Request parameter mode	The default mode is pass-through. You can select pass-through, mapping, or mapping with pass-through. MAPPING: Parameter mapping (filters unknown parameters). PASSTHROUGH: Parameter pass-through. MAPPING_PASSTHROUGH: Mapping with pass-through (passes through unknown parameters). Note If the request parameter mode is pass-through, only path parameters are included in the API definition. Other parameters such as query, header, formdata, and body are ignored.

Step 2: Upload APIs to API Gateway

1. In the file that contains the Controller/RestController class, right-click and select Alibaba Cloud > Upload to API Gateway. This automatically parses all APIs in the current file and triggers an upload dry run.

2. In the Dry Run Result dialog box, confirm that the APIs are parsed correctly, and then click Import to upload the APIs to API Gateway.

   

3. After the import is complete, go to the Published APIs > APIs page in the API Gateway console to verify the result.

Step 3: Test the upload

The sample project in this topic is configured with Swagger. You can visit http://localhost:8080/v2/api-docs to view the actual OAS definition and compare it with the API definition generated by the API Gateway plugin. The API Gateway plugin does not depend on Swagger. After you install the plugin, you can upload APIs directly without running the project.

Spring support details

Spring annotations are flexible in how they define server-side request handling. For example, if you do not specify a method for the @RequestMapping annotation, it handles requests that use any method. In an OAS definition, however, the request method, request path, and request parameters of an API are fixed. The API definition is explicit and specifies how the client is expected to call it. The API Gateway plugin has established conventions to bridge these two different semantics. The following are some examples.

• A parameter without an annotation is assumed to be @RequestParam and is parsed as in=query. Example:

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

  The request parameter isbn is parsed as in=query.

• If the @RequestMapping annotation does not specify a request method, the plugin generates two APIs: one for GET and one for POST. Example:

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

• If a method includes the @PostMapping annotation, the request parameters are parsed as in=formdata. Example:

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

  The request parameters isbn and title are parsed as in=formdata.

• If a method includes the @PostMapping annotation and a method parameter includes the @RequestBody annotation, the plugin infers consumes=application/json if the consumes attribute is not specified. Example:

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

  The request parameter book is parsed as in=body.

Other conventions are consistent with standard Spring usage. Although the plugin makes many inferences, you should still use explicit declarations to define your APIs.

• Declare precise request methods. Use @PostMapping and @GetMapping instead of @RequestMapping.

• When you use @PostMapping, declare a precise consumes value. The consumes value corresponds to the Content-Type of the HTTP request. Common Content-Type values include application/x-www-form-urlencoded and form-data for form parameters, and application/json for JSON data. The API Gateway plugin parses form types and JSON data types differently.

• When you use parameter annotations such as @RequestParam and @RequestHeader, you can use the name attribute to specify the field name and the required attribute to specify whether the parameter is mandatory. This information is reflected in the API definition.

Parsing support details

• When parsing the following common wrapper classes, the plugin unwraps them and parses the fields of the underlying content. The plugin does not support custom wrapper types that require unwrapping.

  • 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

• Built-in variables, such as HttpServletRequest, HttpServletResponse, and HttpSession, are ignored during parsing. The plugin does not support ignoring custom parameter types.

• Generic objects, such as BaseResult<Book>, are supported. If a parameter includes a generic type, specify it explicitly. Do not configure it as just BaseResult. Otherwise, the Book type will not be parsed.

• Enumeration types are supported.

• Collection and Map objects are supported.

• Circular references in request and response objects are supported.

• Attribute configurations in annotations have a higher priority than default configurations. For example, for RequestParam(name="id") String bookId, the plugin uses id as the API field name. By default, the variable name bookId is used as the API field name.