OpenAPI Generated Documentation

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 VMware Tanzu Service Broker manages all p.gateway service instances on the Tanzu Application Service foundation. When you run the cf CLI with any of the service instance commands, such as create-service and bind-service, these are directed towards the Service Broker. In addition to handling service instance commands, the Service Broker also has an OpenAPI v3 compliant auto-generated documentation endpoint. You can acccess this endpoint by finding the Service Broker base URL and then accessing its /openapi endpoint. The Service Broker base URL is available with the following command assuming you have sufficient permissions on Tanzu Application Service to view them:

$ cf service-brokers
Getting service brokers as admin...
OK

Name                URL
scg-service-broker  https://scg-service-broker.sys.mydomain.com

Now you can access the auto-generated OpenAPI v3 endpoint by going to https://scg-service-broker.sys.mydomain.com/openapi given the above base URL for the Service Broker. Application developers can provide their API route configuration to be exposed on an API Gateway service 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 p.gateway service instance and the /openapi endpoint provides an array of these documents for all of the service instances on this Tanzu Application Service foundation.

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:

{
    "host": "my-gateway",
    "sso": {
        "plan": "mysso"
    },
    "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"
  }
],