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 ¶
- func Decode(check func(w http.ResponseWriter, r *http.Request) bool) func(http.Handler) http.Handler
- func DecodeJSON[T any](d *request.Decoder) func(http.Handler) http.Handler
- func Fail(err error, write func(w http.ResponseWriter, r *http.Request)) error
- func Invalid(v *request.Validator) error
- func Request(ctx context.Context) *http.Request
- func RequestErrorHandler(w http.ResponseWriter, r *http.Request, _ error)
- func RequestInContext(next http.Handler) http.Handler
- func Respond(status int, code, message string, opts ...response.ErrorOption) error
- func ResponseErrorHandler(l *slog.Logger) func(w http.ResponseWriter, r *http.Request, err error)
- func ServeSpec(spec []byte) http.Handler
- func WriteError(w http.ResponseWriter, r *http.Request, err error) bool
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 ¶
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 ¶
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 ¶
Invalid returns an error answered with v's field errors (400 VALIDATION_ERROR), logged as Validator.WriteErrors logs them.
func 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 ¶
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 ¶
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 ¶
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 ¶
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. |