Hello!
I’ve been working on the Oaskit library for a while now, and just released a first version.
Since I’ve built JSV I wanted to be able to use the latest JSON schemas specifications with OpenAPI, which is possible since version 3.1.
The OpenAPI specification 4.0 has been delayed, and the 3.2 is on its way, so I needed a solid foundation to support those in the future. Also, I have the feeling that next iterations of the spec will have more LLM-oriented features, so I wanted to be able to follow those evolutions with ease.
What is it?
Oaskit is heavily inspired from OpenApiSpex.
It is a set of macros and plugs that automatically validate incoming HTTP requests based on OpenAPI specifications.
It is built around JSON Schema validation provided by JSV and the operation macro.
Key features
- Request validation plug.
- Leverages JSV error formatter in API responses. An HTML error page is also built-in if you need it (a must have for user-facing prototypes).
- Spec generation from router paths.
- Supports specs from JSON documents or arbirary elixir code.
- Spec JSON generation. Not supporting YAML at the moment, and I don’t plan to. But I’d be happy to open for custom formatters in the codebase.
- Test helper to validate responses in your tests.
Missing features
A couple things are missing and on the roadmap:
- A JSON schema for the built-in error formatter, so you can build 400/415/422 errors in your client generators. My team uses Orval and it’s pretty neat.
A controller to serve the JSON spec, and maybe a controller to serve SwaggerUI or Redoc, though I never use those but I know some love it.- Header validation (Never used it either, as we generally put validation plugs after the authentication/negociation plugs).
I’m also open for ideas!
Quick example
Here’s what defining an operation looks like:
defmodule MyAppWeb.UserController do
use MyAppWeb, :controller
operation :create,
summary: "Create a new user",
request_body: {CreateUserAttrsSchema, description: "The user payload"},
responses: [
created: UserSchema,
unprocessable_entity: ErrorSchema
]
def create(conn, _params) do
# ...
end
end
Getting started
If you want to try it for yourself, the Quickstart Guide covers everything you need to get up and running!
Current status
This is an early release, so while it’s functional and tested, it may have shortcomings and bugs. I need to test it thoroughly in production before calling it production ready.
I’d love to hear your thoughts! Any feedback, bug reports, or feature requests are welcome!
Thanks for reading!
