Manage APIs in API Gateway with Swagger

1. Overview

API Gateway provides a comprehensive set of OpenAPI operations for management. Integrating API Gateway into a CI/CD process primarily involves encapsulating and orchestrating these management operations.

A typical CI/CD workflow for integrating API Gateway includes the following steps:

• Step 1: Automatically obtain the Swagger definition from your backend service code.

• Step 2: Create an API group.

• Step 3: Import the API definition using an OpenAPI operation and deploy the API to different environments.

• Step 4: Apply additional configurations to the API.

2. Example implementation

This section explains the sample code provided. The sample code covers only a basic CI/CD scenario. You can adapt and extend it to fit your requirements.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

@Configuration
@EnableSwagger2
public class SpringFoxConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

{
  "swagger": "2.0",
  "info": {
    "description": "Api Documentation",
    "version": "1.0",
    "title": "Api Documentation",
    "termsOfService": "urn:tos",
    "contact": {
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0"
    }
  },
  "host": "localhost:8080",
  "basePath": "/",
  "tags": [
    {
      "name": "user-controller",
      "description": "User Controller"
    }
  ],
  "paths": {
    "/user": {
      "get": {
        "tags": [
          "user-controller"
        ],
        "summary": "getUser",
        "operationId": "getUserUsingGET",
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          },

2.4 Create an API group

You can create an API group in one of two ways:

2.5 Use the ImportSwagger operation

The key to implementing a CI/CD workflow with API Gateway is to address the following questions:

• Is there an endpoint available to fetch the Swagger definition?

• How can a standard Swagger definition be imported into API Gateway?

As described in section 2.2.2, you can already obtain a Swagger definition that describes all the interfaces and models of the backend service. This section focuses on how to import a standard Swagger definition into API Gateway.

x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  path: '/builtin/echo'
  method: get
  timeout: 10000

Maven dependencies

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-cloudapi20160714</artifactId>
  <version>3.0.38</version>
</dependency>

Obtain the native Swagger file

As mentioned earlier, after you introduce and configure the SpringFox framework, the /v2/api-docs endpoint is automatically generated when the service starts. This endpoint is used to obtain the Swagger definition that describes the backend service.

    private String getSwaggerData(){
        HttpURLConnection connection = null;
        ...
        ...
        String result = null;
        try {
            URL url = new URL(swaggerApiDocUrl);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.connect();
                                                ...
            ...
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
                                                ...
            ...
            connection.disconnect();
        }
        return result;
    }

Configure API Gateway-based Swagger extensions

Correctly configuring Swagger extensions is a critical step in creating APIs that meet your requirements by importing a Swagger file. These API Gateway-based Swagger extensions can be passed through the globalCondition parameter of the ImportSwagger operation. The format for globalCondition is a JSON string.

• key: The name of the API Gateway-based Swagger extension, such as x-aliyun-apigateway-backend.

• value: The value corresponding to the Swagger extension.

In the sample code, configuring a common backend address for the API allows the imported API to access its actual backend service.

For code clarity, based on the description of the HTTP backend service in section 2.5.1, we create the SwaggerBackendInfoBase class to configure backend service information.

public class SwaggerBackendInfoBase {
    private String type;
    private String address;
    public String getType() {
        return type;
    }
    public void setType(String type) {
        this.type = type;
    }
    public String getAddress() {
        return address;
    }
    public void setAddress(String address) {
        this.address = address;
    }
}

We assign a value to the globalCondition parameter based on the user's backend service information.

            // Configure the backend service information required by API Gateway.
            SwaggerBackendInfoBase info = new SwaggerBackendInfoBase();
            info.setType("HTTP");
            info.setAddress("http://www.aliyun.com");
            // Set the backend service information for the API.
            Map<String, String> globalCondition  = new HashMap<>();
            globalCondition.put("x-aliyun-apigateway-backend", JSON.toJSONString(info));

ImportSwagger

In the previous steps, we have created the group, obtained the native Swagger definition, and created the GlobalCondition parameter. We call the ImportSwagger operation provided by API Gateway to import the API and can view the result in the API Gateway console.

The API definition details page (ID 364ea0e74bdd47b5ab05d5449232ae8a) displays the following configuration:

• API group: CiCdGroup5, API Name: getUserUsingGET, Security Authentication: Alibaba Cloud APP, Type: Private, signature algorithm: HmacSHA256

• Request Path: /user, Protocol: HTTP, HTTP Method: GET, request mode: Mapped (Filter Unknown Parameters)

• Backend service type: HTTP, Backend service address: http://www.aliyun.com/user, VPC Channel: Not used, mock: Not used, backend timeout: 10000 ms

• Response Type: JSON (application/json;charset=utf-8)

• Request input parameters, backend service parameters, constant parameters, and custom system parameters are all empty.

2.6 Deploy the API

On the API List page, select the target API group from the API group dropdown list. Select the checkboxes next to the APIs you want to deploy, and then click Deploy at the bottom of the list to deploy the selected APIs in bulk. Deploying an API activates it.

3. Summary

This topic showed how to quickly synchronize APIs from your backend service to API Gateway. API Gateway allows you to focus on developing your backend services by offloading common cross-cutting concerns like authentication and throttling. By using the ImportSwagger operation, you can connect your backend services with API Gateway, significantly reducing the manual configuration process. This also enables the integration of API Gateway configuration and management into your CI/CD workflow.