OpenAPI Middleware

The maniflex/middleware/openapi package customises the auto-generated OpenAPI 3.1 specification served at GET /openapi.json. Every middleware here is registered on the Pipeline.OpenAPI.Generate step at maniflex.After position, so it sees the framework’s generated spec and can mutate it before the Response step serialises it.

SetTitle, SetDescription

Override the default title and description, which are derived from Config.ServiceName:

import "github.com/xaleel/maniflex/middleware/openapi"

server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetTitle("Orders API"),
    maniflex.After,
)
server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetDescription("# Orders API\nProduction endpoints for the orders service."),
    maniflex.After,
)

AddServer

Declares a server URL in servers[]. Repeat for multiple environments:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddServer("https://api.example.com",     "Production"), maniflex.After)
server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddServer("https://staging.example.com", "Staging"),    maniflex.After)

Without AddServer the spec carries no servers array, leaving clients to resolve URLs against the host that served the spec.

AddSecurityScheme

Adds a security scheme to components.securitySchemes and applies it to every operation generated by the framework:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddSecurityScheme("bearerAuth", maniflex.OASSecurityScheme{
        Type:         "http",
        Scheme:       "bearer",
        BearerFormat: "JWT",
    }),
    maniflex.After,
)

Pair with auth.JWTAuth on the runtime side. For API keys, use Type: "apiKey" and set In and Name.

AddExtension

A general-purpose escape hatch — receives the full *maniflex.OpenAPISpec and lets you mutate any part of it:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddExtension(func(spec *maniflex.OpenAPISpec) {
        spec.Info.Contact = &maniflex.OASContact{
            Name:  "API team",
            Email: "api@example.com",
        }
        spec.Info.License = &maniflex.OASLicense{Name: "MIT"}
    }),
    maniflex.After,
)

Use sparingly — anything you can express through the typed helpers is easier to read.

Securing the spec itself

To gate access to /openapi.json, register an Auth middleware on Pipeline.OpenAPI.Auth — it has the same shape as the model-route Auth step:

server.Pipeline.OpenAPI.Auth.Register(auth.RequireRole("internal"))

This is the standard pattern for keeping internal APIs out of the public view while leaving the public surface documented.