See below for how to provide API Gateway metadata and how API route configurations are used to auto-generate OpenAPI v3 documentation.

Accessing Generated OpenAPI v3 Documentation

The Spring Cloud Gateway for Kubernetes operator manages all API Gateway instances on Kubernetes cluster. When you apply any SpringCloudGateway, SpringCloudGatewayRouteConfig or SpringCloudGatewayMapping custom resources onto the Kubernetes cluster, the operator will act to reconcile the environment with those request resource changes. In addition to handling custom resource reconciliation, the operator also has an OpenAPI v3 compliant auto-generated documentation endpoint. You can access this endpoint by exposing the scg-operator service with an ingress and then access its /openapi endpoint. An example ingress applied to the scg-operator service in the spring-cloud-gateway namespace is shown below:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: scg-openapi
  namespace: spring-cloud-gateway
  annotations:
    kubernetes.io/ingress.class: contour
spec:
  rules:
  - host: scg-openapi.mydomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: scg-operator
            port:
              number: 80

Now you can access the auto-generated OpenAPI v3 endpoint by going to https://scg-openapi.mydomain.com/openapi. Application developers can provide their API route configuration to be exposed on an API Gateway instance and those API routes will then be input for generated documentation. This leads to consistent APIs based on API route configuration predicates, filters and metadata across all service instances and the APIs they expose.

It is important to note that a separate OpenAPI v3 document will be generated for each API Gateway instance and the /openapi endpoint provides an array of these documents for all of the instances on this Kubernetes cluster.

Configure OpenAPI Metadata

The following descriptive metadata can be defined when configuring an API Gateway instance:

  • serverUrl: Publicly accessible user-facing URL of this Gateway instance. It is important to note that this configuration does not create a new route mapping for this URL, this is only for metadata purposes to display in the OpenAPI generated documentation.
  • title: Title describing the context of the APIs available on the Gateway instance (default: Spring Cloud Gateway for K8S)
  • description: Detailed description of the APIs available on the Gateway instance (default: Generated OpenAPI 3 document that describes the API routes configured for '[Gateway instance name]' Spring Cloud Gateway instance deployed under '[namespace]' namespace.)
  • version: Version of APIs available on this Gateway instance (default: unspecified)
  • documentation: Location of additional documentation for the APIs available on the Gateway instance

Here is an example of an API Gateway configuration using this descriptive metadata:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  api:
    serverUrl: https://gateway.example.org
    title: My Exciting APIs
    description: Lots of new exciting APIs that you can use for examples!
    version: 0.1.0
    documentation: https://docs.example.org

This will be displayed in the /openapi endpoint of the operator as:

"info": {
  "title": "My Exciting APIs",
  "description": "Lots of new exciting APIs that you can use for examples!",
  "version": "0.1.0"
},
"externalDocs": {
  "url": "https://docs.example.org"
},
"servers": [
  {
    "url": "https://gateway.example.org"
  }
],

PUT/POST/PATCH Request Body Schema

For PUT, POST and PATCH operations, you may add the OpenAPI Schema of Request Body objects.

As in the example below, add model.requestBody property to a route with the proper information.

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: myapp-route-config
spec:
  service:
    name: myapp-service
  routes:
    - id: example-route-id
      predicates:
        - Path=/users/**
      model:
        requestBody:
          description: User to add
          content:
            'application/json':
              schema:
                type: object
                description: User schema
                properties:
                  name:
                    type: string
                  age:
                    type: integer
                    format: int32
                required:
                  - name

The model, alongside with the available HTTP methods and headers will be published under paths.

"paths": {
    "/users/**": {
        "summary": "example-route-id",
        "get": {
            "responses": {
                "200": {
                    "description": "Ok"
                }
            }
        },
        "post": {
            "requestBody": {
                "description": "User to add",
                "content": {
                    "application/json": {
                        "schema": {
                            "required": [
                                "name"
                            ],
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "age": {
                                    "type": "integer",
                                    "format": "int32"
                                }
                            },
                            "description": "User schema"
                        }
                    }
                }
            },
            "responses": {
                "200": {
                    "description": "Ok"
                }
            }
        }

Custom HTTP Responses

In order to add custom HTTP responses for your paths, you may add the OpenAPI Schema of Responses objects.

As in the example below, add model.responses property to a route with the proper information.

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: myapp-route-config
spec:
  service:
    name: myapp-service
  routes:
    - id: example-route-id
      predicates:
        - Path=/users/**
      model:
        responses:
          200:
            description: "Obtain a list of users"
            content:
              application/json:
                schema:
                  type: object
                  description: User schema
                  properties:
                    name:
                      type: string
                    age:
                      type: integer
                      format: int32
          3XX:
            description: "Redirection applied"
            headers:
              X-Redirected-From:
                schema:
                  type: string
                  description: URL from which the request was redirected.
          default:
            description: "Unexpected error"

If you don't provide any HTTP responses, the operator will generate by default a 200 Ok response for every path's operation. Some filters may add custom responses as well to document their inner functionality. You can overwrite these responses too by including them in this section.

check-circle-line exclamation-circle-line close-line
Scroll to top icon