Oaskit - OpenAPI 3.1 based validation for Phoenix

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

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

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?

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.

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

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

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

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

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

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