For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Create ApiDoc resources to pair OpenAPI schemas with your backend services.

An ApiDoc resource represents the OpenAPI schema that is served by a backend Kubernetes service. The portal controller reads ApiDocs to render the API reference documentation in the portal frontend.

Before you begin

1. Follow the Get started guide to install Solo Enterprise for kgateway.
2. Set up a portal. For more information, see Get started with portal.

Deploy a sample app

1. Deploy the petstore sample app. The examples in this guide use this app as the backing service for the ApiDocs resource.

   kubectl apply -f https://raw.githubusercontent.com/kgateway-dev/kgateway.dev/refs/heads/main/assets/docs/examples/petstore.yaml

   Verify that the petstore pod is running.

   kubectl get pods -n default -l app=petstore

   Example output:

   NAME                        READY   STATUS    RESTARTS   AGE
   petstore-6fd9c7f69d-4bntz   1/1     Running   0          10s

2. Create an HTTPRoute for the petstore sample app. If you followed the Get started with portal guide, you already exposed the httpbin app under the api.example.com sample domain. This domain can be used as an umbrella for all APIs that you want to expose in the portal, including the petstore app from this example. To distinguish the routing paths for the different apps, you expose the petstore API endpoints under the /petstore prefix and use a URLRewrite filter to remove that prefix before forwarding requests to the petstore app.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: petstore-route
     namespace: default
   spec:
     parentRefs:
     - name: portal-gateway
       namespace: default
     hostnames:
     - "api.example.com"
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /petstore
       filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /
       backendRefs:
       - name: petstore
         port: 8080
   EOF

Set up ApiDocs

Create an ApiDocs resource that represents the OpenAPI schema that your services serve. You can choose between the following options to provide your OpenAPI schema:

• Manual: You can manually add the OpenAPI schema to the ApiDocs resource and inline each API endpoint in the resource directly.
• URL: Provide a URL that exposes the OpenAPI schema that you want to serve.
• Kube: Fetch the OpenAPI schema from an endpoint that is exposed by an in-cluster Kubernetes service.

kubectl apply -f- <<EOF
apiVersion: portal.solo.io/v1alpha1
kind: ApiDoc
metadata:
  name: petstore-apidoc
  namespace: default
spec:
  source:
    manual:
      content: |
        {
          "openapi": "3.0.0",
          "info": {
            "title": "Petstore API",
            "version": "1.0.0"
          },
          "paths": {
            "/pets": {
              "get": {
                "summary": "List all pets",
                "responses": {
                  "200": {
                    "description": "A list of pets"
                  }
                }
              }
            }
          }
        }
  servedBy:
    name: petstore
    namespace: default
    port: 8080
EOF

kubectl apply -f- <<EOF
apiVersion: portal.solo.io/v1alpha1
kind: ApiDoc
metadata:
  name: petstore-url-apidoc
  namespace: default
spec:
  source:
    url:
      endpoint: "https://petstore3.swagger.io/api/v3/openapi.json"
  servedBy:
    name: petstore
    namespace: default
    port: 8080
EOF

kubectl apply -f- <<EOF
apiVersion: portal.solo.io/v1alpha1
kind: ApiDoc
metadata:
  name: petstore-kube-apidoc
  namespace: default
spec:
  source:
    kube:
      targetRef:
        name: petstore
        port: 8080
      path: /openapi.json
EOF

Verify ApiDocs

1. List the ApiDocs in your namespace. Verify that their READY status is set to True.

   kubectl get apidoc -n default

   Example output:

   NAME                    SOURCE   READY
   petstore-apidoc         Manual   True
   petstore-url-apidoc     URL      True
   petstore-kube-apidoc    Kube     True

2. If an ApiDoc does not show Ready=True, describe the resource to see error details.

   kubectl describe apidoc <name> -n default

   Common issues that you might encounter include:

   • The OpenAPI schema exceeds the 1MB size limit.
   • The schema contains invalid OpenAPI syntax.
   • The servedBy field is missing or the referenced service is unreachable.
   • For URL sources, the endpoint is not accessible or the HTTPS certificate is invalid.

Next