OpenAPI 3.0 Generation

Automatically generate an OpenAPI 3.0 specification from your routes. Get interactive API documentation with Swagger UI — no manual spec writing required.

Setup

Register the OpenAPI plugin in bin/server.go:

import "github.com/CodeSyncr/nimbus/openapi"

app.Use(openapi.New())
// Spec:    GET /openapi.json
// Swagger: GET /docs

How It Works

The plugin scans all registered routes and generates a complete OpenAPI 3.0 spec including paths, parameters, request bodies, and responses. Routes are grouped by tags for organization in the Swagger UI.

• Path parameters extracted from :param segments
• Query parameters from route metadata
• Request/response bodies inferred from handler types
• Authentication requirements from guard middleware

Route Metadata

Add rich metadata to any route for detailed API docs:

app.Router.Get("/api/products", handler, router.RouteMeta{
    Summary:     "List products",
    Description: "Returns a paginated list of products with optional filters",
    Tags:        []string{"Products"},
    Params: []router.ParamMeta{
        {Name: "page", In: "query", Type: "integer", Description: "Page number"},
        {Name: "per_page", In: "query", Type: "integer", Description: "Items per page"},
        {Name: "category", In: "query", Type: "string", Description: "Filter by category"},
    },
    Responses: map[int]router.ResponseMeta{
        200: {Description: "Product list", Schema: []Product{}},
        401: {Description: "Unauthorized"},
    },
})

Real-Life Example: E-Commerce API

// Product endpoints with full OpenAPI metadata
api := app.Router.Group("/api/v1")

api.Get("/products", ctrl.Index, router.RouteMeta{
    Summary: "List products",
    Tags:    []string{"Products"},
    Params: []router.ParamMeta{
        {Name: "search", In: "query", Type: "string", Description: "Search term"},
        {Name: "min_price", In: "query", Type: "number", Description: "Minimum price"},
        {Name: "max_price", In: "query", Type: "number", Description: "Maximum price"},
    },
})

api.Post("/products", ctrl.Store, router.RouteMeta{
    Summary:     "Create product",
    Tags:        []string{"Products"},
    Description: "Creates a new product. Requires admin role.",
    Responses: map[int]router.ResponseMeta{
        201: {Description: "Product created"},
        422: {Description: "Validation errors"},
    },
})

api.Get("/products/:id", ctrl.Show, router.RouteMeta{
    Summary: "Get product details",
    Tags:    []string{"Products"},
    Params: []router.ParamMeta{
        {Name: "id", In: "path", Type: "integer", Description: "Product ID", Required: true},
    },
})

api.Put("/products/:id", ctrl.Update, router.RouteMeta{
    Summary: "Update product",
    Tags:    []string{"Products"},
})

api.Delete("/products/:id", ctrl.Destroy, router.RouteMeta{
    Summary: "Delete product",
    Tags:    []string{"Products"},
})

Generated Spec

The generated spec at /openapi.json follows the OpenAPI 3.0 standard and can be imported into Postman, Insomnia, or any API client.

{
  "openapi": "3.0.0",
  "info": {
    "title": "MyApp API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/v1/products": {
      "get": {
        "summary": "List products",
        "tags": ["Products"],
        "parameters": [
          {"name": "search", "in": "query", "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {"description": "Product list"}
        }
      }
    }
  }
}

Programmatic Export: app.DumpOpenAPI()

Export the full OpenAPI 3.0 specification file programmatically during the warmup phase for CI/CD or client generation pipelines:

app := bin.Boot()
app.SetMode(nimbus.ModeWarmup)

// Automatically warms up the app and exports the OpenAPI spec
if err := app.DumpOpenAPI("docs/openapi.json"); err != nil {
    log.Fatal(err)
}

Best Practices

• Add RouteMeta to all API endpoints for complete documentation
• Use Tags to group related endpoints in Swagger UI
• Document all response codes including errors (401, 422, 500)
• Mark required parameters with Required: true
• Export the spec with app.DumpOpenAPI() for API client generation (Go, TypeScript, Python)