openapi

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package openapi holds the glue between an OpenAPI contract-first server generated by oapi-codegen (chi-server + strict-server) and vogel's request and response packages.

The pattern it supports: api/openapi.yaml is the source of truth, the strict server is generated from it, and the routes are still registered by hand on chi so each keeps its authentication, RequirePermission and rate limits next to it. The generated parameter binding is bypassed (parameters are declared with x-go-type: string) and handlers read the request through Request, validating it with request.Validator, so error messages and envelopes stay exactly the ones vogel sends. Successes use the generated typed responses; errors are returned as Go errors that carry their vogel writer:

func (h *Handler) GetEntry(ctx context.Context, req gen.GetEntryRequestObject) (gen.GetEntryResponseObject, error) {
    r := openapi.Request(ctx)
    v := request.NewValidator()
    id := v.UUIDParam(r, "id")
    if v.HasErrors() {
        return nil, openapi.Invalid(v)
    }
    ...
}

Wire the strict server with ResponseErrorHandler and RequestErrorHandler:

api := gen.NewStrictHandlerWithOptions(handlers, nil, gen.StrictHTTPServerOptions{
    RequestErrorHandlerFunc:  openapi.RequestErrorHandler,
    ResponseErrorHandlerFunc: openapi.ResponseErrorHandler(logger),
})

The package does not import oapi-codegen: it only depends on net/http and vogel.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Decode

func Decode(check func(w http.ResponseWriter, r *http.Request) bool) func(http.Handler) http.Handler

Decode returns a middleware that runs check on the request body before the generated strict server decodes it, so a malformed body is rejected with the project's own responses (status, code and messages) instead of the generated decoder's. check writes the rejection itself and returns false; when it returns true, the body is rewound so the generated decoder reads it from the start.

func DecodeJSON

func DecodeJSON[T any](d *request.Decoder) func(http.Handler) http.Handler

DecodeJSON returns a Decode middleware that checks the body with vogel's JSON decoder into a fresh T: Content-Type, size limit, unknown fields, trailing data and type errors answer 400/413/415 exactly as request.JSON does. d is the decoder to use (for its Messages or options); nil uses request.JSON.

func Fail

func Fail(err error, write func(w http.ResponseWriter, r *http.Request)) error

Fail returns an error that, returned from a strict handler, makes ResponseErrorHandler answer with write. err is the cause, kept for errors.Is/As; it may be nil.

func Invalid

func Invalid(v *request.Validator) error

Invalid returns an error answered with v's field errors (400 VALIDATION_ERROR), logged as Validator.WriteErrors logs them.

func Request

func Request(ctx context.Context) *http.Request

Request returns the request RequestInContext stored. A handler reached without that middleware is a wiring bug, so it panics instead of guessing (vogel's Recovery turns the panic into a 500).

func RequestErrorHandler

func RequestErrorHandler(w http.ResponseWriter, r *http.Request, _ error)

RequestErrorHandler is the strict server's RequestErrorHandlerFunc: the generated decoder could not read the body, so it answers 400 INVALID_JSON and logs the rejection. With Decode or DecodeJSON in front of the operation, vogel has already rejected such bodies with its own messages.

func RequestInContext

func RequestInContext(next http.Handler) http.Handler

RequestInContext stores the request in its own context so strict handlers, which only receive a context, can read it with Request. Install it as the last middleware of each contract route: the stored request is the one it sees, so context values added after it are not in it.

func Respond

func Respond(status int, code, message string, opts ...response.ErrorOption) error

Respond returns an error answered with response.ErrorWith(status, code, message, opts...).

func ResponseErrorHandler

func ResponseErrorHandler(l *slog.Logger) func(w http.ResponseWriter, r *http.Request, err error)

ResponseErrorHandler returns the strict server's ResponseErrorHandlerFunc: it writes the response an error from Fail, Respond or Invalid carries, and answers any other error with a 500 INTERNAL_ERROR, logging it to l (or slog.Default() when l is nil).

func ServeSpec

func ServeSpec(spec []byte) http.Handler

ServeSpec serves the raw OpenAPI document as application/yaml. Serve the embedded file itself rather than oapi-codegen's embedded spec, which is re-encoded and does not keep the document byte for byte.

func WriteError

func WriteError(w http.ResponseWriter, r *http.Request, err error) bool

WriteError writes the response err carries, if any, and reports whether it did. err may wrap the error Fail returned.

Types

This section is empty.

Directories

Path Synopsis
Package openapitest holds test helpers that keep a hand-wired chi router and the Go types it serves in sync with an OpenAPI document.
Package openapitest holds test helpers that keep a hand-wired chi router and the Go types it serves in sync with an OpenAPI document.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL