Oaskit - OpenAPI 3.1 based validation for Phoenix

[lud]

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!

oaskit

GitHub - lud/oaskit: A fully featured OpenAPI Request validator for...

[lud]

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

[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).

[Asd]

Hi, nice library. I have one question:
It looks very very very similar to open_api_spex. Whats the difference between your library and open_api_spex and why/when should I choose your one?

[lud]

Hello,

Yes it’s very inspired from OpenApiSpex, basically the same thing. OpenApiSpex is based on OpenAPI 3.0 and Oaskit on OpenAPI 3.1.

Those two version are not really compatible infortunately. 3.1 works with standard JSON schemas and I needed that so I built Oaskit.

[phcurado]

@lud awesome library, using OpenAPI 3.1 and following JSON Schema spec is just what I need it

[lud]

Oaskit JSON shema validation is based on JSV, you might want to have a look if you are going to work with schemas!

[phcurado]

I did use JSV to validate the schemas I was generating with my library, another great addition to the elixir ecosystem .

[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

[lud]

Just bumping my own topic as dependabot will trigger this morning and there is an important step to do before upgrading

[lud]

Hello!

Oaskit now has experimental support for extensions, limited on the operation only.

You can add any key to the operation macro and it will be forwarded into the conn.private.oaskit.extensions map that controllers and subsequent plugs can access.

If you do not use macros from Oaskit, this also works with unknown keys that are defined in your OpenAPI specification document (from YAML for instance) that you feed to Oaskit.

If you do use the macros, and generate JSON dumps of your specification with mix openapi.dump, only the extensions prefixed with x- are exported.

Here is a complete example of how it could be used:

defmodule MyAppWeb.UserController do
  use MyAppWeb, :api_controller
  use JSV.Schema

  # This could be defined by `use MyAppWeb, :api_controller` directly, below 
  # the Oaskit request validation plug
  plug MyAppWeb.Plugs.RateLimiter

  defschema CommentRequest,
    message: string(),
    author: string()

  defschema CommentResponse,
    id: integer(),
    message: string(),
    author: string()

  operation :create,
    # Generic OpenAPI fields
    summary: "Post a comment",
    request_body: CommentRequest,
    responses: [
      ok: CommentResponse, 
      bad_request: MyAppWeb.Schemas.BadRequest
    ],

    # Public extensions with `x-`
    "x-rate-limit": 100,
    
    # Private extensions
    skip_antispam_for: :admin

  def create(conn, params) do
    %CommentRequest{} = comment = body_params(conn)

    spam_comment? =
      if user_role(conn) == conn.private.oaskit.extensions.skip_antispam_for do
        false
      else
        spam_comment?(comment)
      end

    if spam_comment? do
      reject_comment(conn)
    else
      create_comment(conn, comment)
    end
  end
end

You can find more information in the short extensions guide. I hope this can cover most customization needs for now, we’ll see how it is used and how we can make it evolve in the future.

Many thanks to maximejimenez for the help!

Cheers