openapi

Documentation

Overview

Package openapi provides OpenAPI pipeline middleware for enriching the auto-generated spec with security schemes, servers, examples, and extensions.

Index

• func AddExtension(patcher SpecPatcher) maniflex.OpenAPIMiddlewareFunc
• func AddSecurityScheme(name string, scheme maniflex.OASSecurityScheme) maniflex.OpenAPIMiddlewareFunc
• func AddServer(url, description string) maniflex.OpenAPIMiddlewareFunc
• func AddTag(name, description string) maniflex.OpenAPIMiddlewareFunc
• func InjectRequestExample(target OperationTarget, name string, value any) maniflex.OpenAPIMiddlewareFunc
• func SetDescription(md string) maniflex.OpenAPIMiddlewareFunc
• func SetTitle(title string) maniflex.OpenAPIMiddlewareFunc
• func SetVersion(version string) maniflex.OpenAPIMiddlewareFunc
• type OperationTarget
• type SpecPatcher

Functions

func AddExtension

func AddExtension(patcher SpecPatcher) maniflex.OpenAPIMiddlewareFunc

AddExtension applies an arbitrary patch function to the spec. The function runs after the Generate step (register with maniflex.After). Use it for x- extensions, gateway annotations, or any structural change.

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddExtension(func(spec *maniflex.OpenAPISpec) {
        // Kong gateway route annotation
        for path, item := range spec.Paths {
            if item.Post != nil {
                // item.Post extensions would go here via a custom type
                _ = path
            }
        }
    }),
    maniflex.After,
)

func AddSecurityScheme

func AddSecurityScheme(name string, scheme maniflex.OASSecurityScheme) maniflex.OpenAPIMiddlewareFunc

AddSecurityScheme adds a named security scheme to components/securitySchemes. Register it with maniflex.After on the Generate step so the spec already exists.

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

func AddServer

func AddServer(url, description string) maniflex.OpenAPIMiddlewareFunc

AddServer appends a Server Object to the spec. Useful when the API is served behind a reverse proxy at a different base path, or when you want to expose staging and production URLs.

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

func AddTag

func AddTag(name, description string) maniflex.OpenAPIMiddlewareFunc

AddTag appends a Tag Object to the spec. Tags appear as collapsible groups in Swagger UI. maniflex already generates one tag per model; use AddTag to add cross-cutting or documentation-only tags.

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

func InjectRequestExample

func InjectRequestExample(target OperationTarget, name string, value any) maniflex.OpenAPIMiddlewareFunc

InjectRequestExample adds an example body to the request body of a specific operation. This makes Swagger UI's "Try it out" feature pre-populate with realistic values.

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

func SetDescription

func SetDescription(md string) maniflex.OpenAPIMiddlewareFunc

SetDescription sets the spec's info.description field. Markdown is supported by most OpenAPI tooling including Swagger UI and Redoc.

server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetDescription("# My API\n\nWelcome to the API docs."),
    maniflex.After,
)

func SetTitle

func SetTitle(title string) maniflex.OpenAPIMiddlewareFunc

SetTitle sets the spec's info.title field.

server.Pipeline.OpenAPI.Generate.Register(openapi.SetTitle("Blog Platform API"), maniflex.After)

func SetVersion

func SetVersion(version string) maniflex.OpenAPIMiddlewareFunc

SetVersion sets the spec's info.version field.

Types

type OperationTarget

type OperationTarget struct {
	// Path is the URL path as it appears in spec.Paths, e.g. "/posts".
	Path string
	// Method is one of "get", "post", "patch", "delete".
	Method string
}

OperationTarget identifies which path + HTTP method to inject examples into.

type SpecPatcher

type SpecPatcher func(spec *maniflex.OpenAPISpec)

SpecPatcher is a function that receives the full spec and can mutate it freely. Use this for anything not covered by the other helpers.