Middleware for the Echo web server to perform validation of incoming requests via an OpenAPI specification.

This project is a lightweight wrapper over the excellent kin-openapi library's openapi3filter package.

This is intended to be used with code that's generated through oapi-codegen, but should work otherwise.

⚠️ This README may be for the latest development version, which may contain unreleased changes. Please ensure you're looking at the README for the latest release version.

You can add the middleware to your project with:

go get github.com/oapi-codegen/echo-middleware

There is a full example of usage in the Go doc for this project.

A simplified version of this code is as follows:

rawSpec := `
openapi: "3.0.0"
# ...
`
spec, _ := openapi3.NewLoader().LoadFromData([]byte(rawSpec))

// NOTE that we need to make sure that the `Servers` aren't set, otherwise the OpenAPI validation middleware will validate that the `Host` header (of incoming requests) are targeting known `Servers` in the OpenAPI spec
// See also: Options#SilenceServersWarning
spec.Servers = nil

e := echo.New()
e.POST("/resource", func(c echo.Context) error {
    fmt.Printf("%s /resource was called\n", c.Request().Method)

    return c.NoContent(http.StatusNoContent)
})

// create middleware
mw := middleware.OapiRequestValidatorWithOptions(spec, &middleware.Options{
    Options: openapi3filter.Options{
        AuthenticationFunc: authenticationFunc,
    },
})

e.Use(mw)

// now all HTTP routes will be handled by the middleware, and any requests that are invalid will be rejected

This middleware enables openapi3filter.Options.KeepValidatedValue by default. After a request body passes validation, the c.Request().Body seen by handlers implements interface{ ValidatedValue() any }, returning the decoded value that was validated (schema defaults included), and the body can still be read as usual. This lets a handler, such as an oapi-codegen strict server that supports it, bind exactly the value that was validated rather than decoding the body a second time, which closes gaps where a second decode could disagree with validation (for example, encoding/json matching object keys case-insensitively, so {"role":"user","ROLE":"admin"} validates as role: user but binds as Role: "admin").

To opt out, for instance to limit memory retention for very large request bodies, set Options.DiscardValidatedValue: true. This takes precedence over Options.Options.KeepValidatedValue.

Any middleware that runs after the validator and replaces the request body (decompression, size limiting, logging wrappers, ...) hides the validated value from handlers, so such middleware belongs before the validator.

As this project is a lightweight wrapper over kin-openapi's openapi3filter package, it's likely that any bugs/features are better sent upstream.

However, it's worth raising an issue here instead, as it'll allow us to triage it before it goes to the kin-openapi maintainers.

Additionally, as oapi-codegen contains a number of middleware modules, we'll very likely want to implement the same functionality across all the middlewares, so it may take a bit more coordination to get the changes in across our middlewares.

The kin-openapi project - which we 💜 for providing a great library and set of tooling for interacting with OpenAPI - is a pre-v1 release, which means that they're within their rights to push breaking changes.

This may lead to breakage in your consuming code, and if so, sorry that's happened!

We'll be aware of the issue, and will work to update both the core oapi-codegen and the middlewares accordingly.