Skip to main content

OpenAPI Synchronization

OpenAPI Synchronization

Single source of truth for API specification management across the BlueFly.io ecosystem.

Overview

OpenAPI specifications are synchronized from individual projects to the centralized API Schema Registry, which powers the interactive Swagger UI at https://docs.blueflyagents.com/api/.

Direction: Project openapi.yaml -> API Schema Registry -> Documentation Portal

How It Works


  Your Project                                                       
   openapi.yaml         # Your API specification                  
   .gitlab-ci.yml       # Includes sync job                       
                                                                    
                                                                    
     
    API Schema Registry                                            
     openapi/<project-name>.yaml                                
     
                                                                    
                                                                    
     
    Technical Docs Portal                                          
     /api/<project-name>/  (Swagger UI)

Quick Start

1. Add OpenAPI Spec to Your Project

Create openapi.yaml in your project root:

openapi: 3.1.0
info:
  title: Your API Name
  version: 1.0.0
  description: API description
paths:
  /api/v1/resource:
    get:
      summary: List resources
      responses:
        '200':
          description: Success

2. Include Sync Component in CI

Add to your .gitlab-ci.yml:

include:
  - project: 'blueflyio/agent-platform/gitlab_components'
    ref: main
    file: '/templates/openapi-sync.yml'

# Sync runs automatically on main branch commits

3. Verify Sync

After merge to main:

Configuration Options

CI Variables

VariableDefaultDescription
OPENAPI_FILEopenapi.yamlPath to your OpenAPI specification
OPENAPI_TARGET_NAME$CI_PROJECT_NAMEName in the registry (e.g., mcp-registry)
OPENAPI_SYNC_BRANCHmainBranch to sync from

Example: Custom Configuration

variables:
  OPENAPI_FILE: docs/api/openapi.yaml
  OPENAPI_TARGET_NAME: my-custom-api

include:
  - project: 'blueflyio/agent-platform/gitlab_components'
    ref: main
    file: '/templates/openapi-sync.yml'

Commands

BuildKit CLI

# Sync current project's OpenAPI to registry
buildkit openapi sync

# Sync with custom options
buildkit openapi sync --file docs/openapi.yaml --name my-api

# Validate OpenAPI spec before sync
buildkit openapi validate

# List all synced APIs in registry
buildkit openapi list

# Generate TypeScript types from OpenAPI
buildkit openapi generate --output src/types/api.ts

Manual Sync (Advanced)

# Clone registry
git clone https://gitlab.com/blueflyio/agent-platform/api-schema-registry.git

# Copy your spec
cp openapi.yaml api-schema-registry/openapi/${PROJECT_NAME}.yaml

# Commit and push
cd api-schema-registry
git add openapi/
git commit -m "chore: sync ${PROJECT_NAME} OpenAPI spec"
git push

OpenAPI Best Practices

File Structure

your-project/
 openapi.yaml              # Main specification (required)
 openapi/                   # Optional: Split specs
    paths/                 # Path definitions
    components/            # Reusable components
    schemas/               # Schema definitions
 docs/
     openapi.html          # Generated ReDoc HTML (optional)

Specification Standards

  1. Version: Use OpenAPI 3.1.0 (or 3.0.3 minimum)
  2. Info Block: Include title, version, description, contact
  3. Servers: Define base URLs for each environment
  4. Tags: Group related endpoints
  5. Security: Define authentication schemes
  6. Examples: Include request/response examples

Example: Complete Specification

openapi: 3.1.0
info:
  title: MCP Registry API
  version: 2.0.0
  description: |
    Model Context Protocol server registry for managing
    AI tool integrations across the platform.
  contact:
    name: BlueFly.io
    url: https://bluefly.io
    email: api@bluefly.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.blueflyagents.com/v2
    description: Production
  - url: https://api-staging.blueflyagents.com/v2
    description: Staging
  - url: http://localhost:8080/v2
    description: Local Development

tags:
  - name: Servers
    description: MCP server management
  - name: Tools
    description: Tool discovery and invocation

security:
  - bearerAuth: []

paths:
  /servers:
    get:
      summary: List registered MCP servers
      tags: [Servers]
      responses:
        '200':
          description: List of servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerList'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ServerList:
      type: object
      properties:
        servers:
          type: array
          items:
            $ref: '#/components/schemas/Server'
    Server:
      type: object
      required: [id, name, url]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        url:
          type: string
          format: uri

Drupal Module Integration

For Drupal modules, follow this pattern:

Directory Structure

your_module/
 openapi.yaml              # API specification
 openapi.html              # ReDoc static HTML
 tools/
     openapi.redoc.config.json

Generate ReDoc HTML

# Install redoc-cli
npm install -g @redocly/cli

# Generate static HTML
redocly build-docs openapi.yaml --output openapi.html

Link in README

Replace duplicated content in your README with:

## API Documentation

See [openapi.yaml](./openapi.yaml) for the complete API specification.

**Interactive Docs**: https://docs.blueflyagents.com/api/your-module/

For synchronization details, see the [OpenAPI Synchronization Guide](https://gitlab.com/blueflyio/agent-platform/technical-docs/-/wikis/reference/openapi-synchronization).

Troubleshooting

Sync Failed

  1. Check CI job logs: Look for the sync:openapi job
  2. Validate spec: Run buildkit openapi validate
  3. Verify permissions: Ensure project has access to registry

Spec Not Appearing in Portal

  1. Wait for build: Portal rebuilds every 30 minutes
  2. Force rebuild: Trigger manual pipeline in technical-docs
  3. Check registry: Verify file exists in api-schema-registry

Validation Errors

# Common issues:
# - Missing required fields (info.title, info.version)
# - Invalid $ref paths
# - Unsupported OpenAPI features

# Fix with:
buildkit openapi validate --verbose

Related Links

Version: 1.0.0 Created: 2026-01-01 Maintainer: BlueFly.io Platform Team