go-swagger-hub

README

go-swagger-hub

A Go library for centralizing and aggregating Swagger/OpenAPI specifications from multiple microservices into a unified API documentation hub.

Features

• Spec Builder — Programmatically generate OpenAPI 3.0 specs from Go struct types via reflection. Auto-generates CRUD endpoints for generic router patterns.
• Spec Merger — Combine multiple per-service OpenAPI specs into a single aggregated spec with path rewriting, schema prefixing, conflict detection, and validation.
• Swagger UI Handler — Gin middleware to serve Swagger UI with an embedded aggregated spec.
• Shared Schemas — Standard response/error schemas, security schemes (JWT, API Key, OAuth2, Basic), and HTTP status codes.
• CI/CD Ready — CLI tool for merge + validate, designed for GitHub Actions / GitLab CI pipelines.

Packages

Package	Description
oas	Lightweight OpenAPI 3.0 type wrappers (map-based, zero external deps)
schemas	Shared schemas, security schemes, standard tags, HTTP codes
builder	Reflection-based spec builder for generating OpenAPI from Go structs
merger	CLI tool + merge algorithm for combining multiple service specs
swaggerui	Gin handler for serving Swagger UI + embedded spec

Quick Start

1. Generate a per-service spec

package main

import (
    "flag"
    "reflect"
    "github.com/natifdevelopment/go-swagger-hub/builder"
)

type User struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"John"`
}

type UserRequest struct {
    Name string `json:"name" example:"John"`
}

func main() {
    output := flag.String("o", "docs/swagger.json", "Output path")
    flag.Parse()

    sb := builder.NewSpecBuilder("My API", "My API docs", "1.0.0", "/api/v1")
    sb.RegisterModule("/users", "Users",
        reflect.TypeOf(User{}), reflect.TypeOf(UserRequest{}))

    spec := sb.Build()
    // Write spec to JSON file...
}

2. Merge specs from multiple services

Create a services.yaml config (see merger/services.example.yaml):

version: "1.0"
gateway:
  title: "My API Gateway"
  version: "1.0.0"
  server_url: "http://localhost:8080"
services:
  - key: my-api
    name: "My Core API"
    spec_path: "artifacts/my-api.swagger.json"
    schema_prefix: "MyApi"
    default_security: BearerAuth
    required: true
output:
  path: "docs/openapi-aggregated.json"

Run the merger:

go run ./merger/cmd/merge -config services.yaml -o docs/openapi-aggregated.json -v

3. Serve Swagger UI in your gateway

package main

import (
    _ "embed"
    "github.com/gin-gonic/gin"
    swaggerui "github.com/natifdevelopment/go-swagger-hub/swaggerui"
)

//go:embed docs/openapi-aggregated.json
var spec []byte

func main() {
    swaggerui.SetSpec(spec)
    r := gin.Default()
    r.GET("/swagger/doc.json", swaggerui.SpecHandler())
    r.GET("/swagger/*any", swaggerui.Handler())
    r.Run(":8080")
}

CLI Usage

go-swagger-hub merger - Merge OpenAPI specs from multiple services

Usage:
  merge -config services.yaml [flags]

Flags:
  -config string       Path to merge config (default "services.yaml")
  -o string            Output JSON path
  -yaml string         Output YAML path (optional)
  -report string       Merge report path
  -validate-only       Validate only, don't write output
  -strict              Fail on warnings too
  -v                   Verbose output

Merge Features

• Path rewriting — Rewrite service paths to gateway public paths (e.g., /api/v1 → /auth/v1)
• Schema prefixing — Prefix non-shared schema names per-service to avoid collisions
• Shared schema dedup — Standard schemas (StandardResponse, StandardError) are deduplicated
• Security injection — Per-endpoint security based on public_paths config
• Validation — Duplicate paths, broken references, missing tags, missing security
• Report — JSON report with per-service stats, conflicts, and validation results

License

MIT