openapi-aggregator-operator

OpenAPI Aggregator Operator

Kubernetes operator that discovers and aggregates OpenAPI/Swagger specifications from services running in your cluster. It provides a unified Swagger UI interface to browse and test all your APIs in one place.

Quick Start

1. Installation

# Install the operator
kubectl apply -f https://raw.githubusercontent.com/hellices/openapi-aggregator-operator/main/install.yaml

# Verify the installation
kubectl get pods -n openapi-aggregator-system

2. Configure Services

Add these annotations to your services that expose OpenAPI/Swagger specs:

metadata:
  annotations:
    openapi.aggregator.io/swagger: "true"      # Required
    openapi.aggregator.io/path: "/v2/api-docs" # Optional (default: /v2/api-docs)
    openapi.aggregator.io/port: "8080"         # Optional (default: 8080)

3. Create Aggregator Instance

kubectl apply -f - <<EOF
apiVersion: observability.aggregator.io/v1alpha1
kind: OpenAPIAggregator
metadata:
  name: openapi-aggregator
spec:
  labelSelector: {}  # Optional: Filter services by labels
EOF

4. Access Swagger UI

kubectl port-forward -n openapi-aggregator-system svc/openapi-aggregator-openapi-aggregator-swagger-ui 9090:9090

Then open http://localhost:9090 in your browser.

Features

• 🔍 Auto-discovery: Automatically finds services with OpenAPI specifications using annotations
• 🔄 Real-time Updates: Fetches specifications in real-time and updates every 10 seconds
• 🎯 Configurable Endpoints: Customize OpenAPI spec paths and ports through annotations
• 🌐 Unified UI: Single Swagger UI interface to browse all discovered APIs
• 📝 Service Information: Displays service metadata including namespace and resource type
• ⚡ Zero-config Services: Works with any service that exposes an OpenAPI/Swagger specification

5. Ingress/Route Integration

You can expose the Swagger UI through Ingress or OpenShift Route.

Using Kubernetes Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: swagger-ui
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /swagger-ui(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: openapi-aggregator-openapi-aggregator-swagger-ui
            port:
              number: 9090

And set the environment variable in the deployment:

env:
- name: SWAGGER_BASE_PATH
  value: /swagger-ui

Using OpenShift Route

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: swagger-ui
spec:
  to:
    kind: Service
    name: openapi-aggregator-openapi-aggregator-swagger-ui
  port:
    targetPort: swagger-ui

Project Architecture

Components

1. Controller:

   • Watches for services with OpenAPI annotations
   • Collects service metadata and OpenAPI spec URLs
   • Updates status every 10 seconds

2. Swagger UI Server:

   • Serves unified Swagger UI interface
   • Fetches OpenAPI specs in real-time
   • Provides API selection and documentation

Project Structure

.
├── api/             # API definitions and generated code
├── cmd/             # Main application entry point
├── config/          # Kubernetes manifests and kustomize configs
├── internal/        # Internal packages
│   └── controller/  # Operator controller logic
└── pkg/            
    ├── swagger/     # Swagger UI server implementation
    └── version/     # Version information

Development Guide

Prerequisites

• Go 1.22+
• Kubernetes 1.24+
• kubectl
• kustomize
• controller-gen

Installation Methods

1. Quick Install (For Users)

kubectl apply -f https://raw.githubusercontent.com/hellices/openapi-aggregator-operator/main/install.yaml

2. Development Install

# Clone and build
git clone https://github.com/hellices/openapi-aggregator-operator
cd openapi-aggregator-operator
make install
make deploy

3. OLM Install (Advanced)

For installation via Operator Lifecycle Manager, see detailed instructions in OLM Installation Guide.

Development Environment Setup

1. Deploy the test service:

# First, deploy the test service that provides OpenAPI specs
kubectl apply -f config/samples/test-service.yaml

# Port forward the test service to localhost:8080
kubectl port-forward svc/test-service 8080:8080

1. Run the operator in development mode:

# Run locally
make run

# Run tests
make test

# Build and push image
make docker-build docker-push

# Generate manifests
make manifests

Note: When running the operator in development mode with make run, ensure that the test service is running and port-forwarded to localhost:8080. This is required for the operator to properly fetch and display the OpenAPI specifications in the Swagger UI.

Version Management

• Version is managed in versions.txt
• Used for Docker images, releases, and binary info
• Format: ghcr.io/hellices/openapi-aggregator-operator:<version>

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.