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

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

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

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.