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

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.