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