lud

Oaskit - OpenAPI 3.1 based validation for Phoenix

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!

https://github.com/lud/oaskit

11 comments

/phoenix #library #openapi #oaskit

12 901 11

2025-12-18 17:55:02 UTC

Most Liked

lud

Hey everyone!

This is an important update for Oaskit with one breaking change!

The library can now automatically delegate authorization of requests to a custom plug of yours, using the security requirements defined on operations.

Please read this post before upgrading if you’re using the library.

The security requirements definitions on operations are now checked. If your OpenAPI specification defines security options, Oaskit will now expect a custom plug that you provide to authorize requests.

From now on, Oaskit will automatically respond to requests on those operations with a 401 HTTP Error unless you provide a custom plug to handle authorization.

This is all covered in a new security guide.

To keep the current behaviour of the library (not verifying authorization), please update your code to set the :security option to false.

plug Oaskit.Plugs.ValidateRequest,
  security: false

Security is important so any feedback will be highly appreciated! Also, many thanks to @MrYawe for the motivation and the bug reports

Changelog

[0.6.0] - 2025-10-11

Features

Added operation-level security check using user-defined plugs
Added support for root level security requirements
[breaking] Handling security is now mandatory

Bug Fixes

Ensure response body is a binary in Oaskit.Test.valid_response (#23)
Fixed normalization of %Reference{} structs

How do I know if I am concerned by this update?

You are concerned if your OpenAPI specification defines security at the root level:

---
openapi: 3.1.1
info:
  title: Oaskit Security API
  version: 0.0.0
servers:
- url: http://localhost:5001/
# Global security
security:
- global:
  - some:global1
  - some:global2

Or at the operation level:

---
openapi: 3.1.1
info:
  title: Oaskit Security API
  version: 0.0.0
servers:
- url: http://localhost:5001/
paths:      
  "/example":
    post:
      operationId: "..."
      # Operation Level security
      security:
      - someApiKey:
        - some:scope1
        - some:scope2
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: "..."

You are also concerned if your were using the operation macro by passing the :security option (which was not used but could be defined):

operation :create_post,
  operation_id: "CreatePost",
  request_body: PostSchema,
  security: [%{api_key: ["post:read", "post:create"]}]

def create_post(conn, _) do
  # ...
end

Thank you for using Oaskit! Have a nice evening

Post #9

lud

I just released version 0.2 with a guide on how to use the library with an existing OpenAPI JSON document instead of defining the operations in the controller: Using an External Specification — oaskit v0.2.0 cc @mayel .

(Spoiler, there is still a tiny macro to use).

Post #3

lud

I’ve just released a new version with a controller that can serve the spec and Redoc ui

Post #1

Last Post!

lud

Hello,

I just released Oaskit 0.9 that uses the new unprocessable_content status from Plug, instead of unprocessable_entity.

On the HTTP side of things, it’s sill a 422 error, so no changes, but in Typescript/Javascript client it can be important to change it if you match the returned kind property in the errors from the built-in error handler.

Cheers!

Post #12