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,
)

SetVersion

Overrides the spec’s info.version, which is otherwise the framework default. Use it to surface your service’s own release version in the published spec:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetVersion("2.1.0"),
    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.

AddTag

Appends a Tag Object to the spec. Tags render as collapsible groups in Swagger UI; maniflex already emits one tag per model, so use AddTag for cross-cutting or documentation-only groupings. A tag whose name already exists is not duplicated.

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddTag("Authentication", "Endpoints related to user authentication"),
    maniflex.After,
)

InjectRequestExample

Attaches an example request body to a specific operation so Swagger UI’s “Try it out” pre-populates with realistic values. The operation is named by path and lower-case method:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.InjectRequestExample(
        openapi.OperationTarget{Path: "/posts", Method: "post"},
        "Example post", map[string]any{
            "title":  "Hello World",
            "body":   "My first post.",
            "status": "draft",
        }),
    maniflex.After,
)

The example is only applied when the target operation and its request body exist in the generated spec; an unmatched target is a no-op.

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.Description += "\n\nContact the API team at [email protected]."
    }),
    maniflex.After,
)

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

Securing the spec itself

Generated specifications are not mounted by default. Prefer one router-level policy for both OpenAPI and AsyncAPI:

cfg.Documentation = maniflex.DocumentationConfig{
    Middleware: []maniflex.HTTPMiddleware{
        maniflex.AdaptAuth(
            auth.JWTAuth(jwtSecret),
            auth.RequireRole("internal"),
        ),
    },
}

Pipeline.OpenAPI.Auth remains available for OpenAPI-specific middleware, but its function type is OpenAPIMiddlewareFunc; model-route helpers such as auth.JWTAuth and auth.RequireRole must be used through AdaptAuth as shown above.