Oaskit behaviour (oaskit v0.6.0)

The main API to work with OpenAPI specifications.

This module can be used to define a specification module that will then be used in your Phoenix router and controllers.

Example

defmodule MyAppWeb.OpenAPISpec do
  alias Oaskit.Spec.Paths
  alias Oaskit.Spec.Server
  use Oaskit

  @impl true
  def spec do
    %{
      openapi: "3.1.1",
      info: %{title: "My App API", version: "1.0.0"},
      servers: [Server.from_config(:my_app, MyAppWeb.Endpoint)],
      paths: Paths.from_router(MyAppWeb.Router, filter: &String.starts_with?(&1.path, "/api/"))
    }
  end
end

Summary

Types

cache_action()

A cache action given to cache/1. Oaskit will use keys of type cache_key/0 when calling the cache.

cache_key()

The cache keys used by this module when calling cache/1.

Callbacks

cache(cache_action)

This callback is used to cache the built version of the OpenAPI specification, with JSV schemas turned into validators.

cache_variant()

This function is intended to change cache keys at runtime. The variant is any term used as the last element of a cache_key/0.

jsv_opts()

Returns the options that will be passed to JSV.build/2 when building the spec for the implementation module.

spec()

This function should return the OpenAPI specification for your application.

Functions

cached(spec_module, cache_key, generator)

Retrieves a cached from the implementation module.

cast!(module)

Validates the given OpenAPI specification module returns a representation of the specification using structs such as Oaskit.Spec.OpenAPI, Oaskit.Spec.Response, etc.

default_jsv_opts()

Default options used for the JSV.build/2 function when building schemas

normalize_spec!(data)

Normalizes OpenAPI specification data.

to_json!(module, opts \\ [])

Returns a JSON representation of the given OpenAPI specification module.

Types

cache_action()

@type cache_action() ::
  {:get, key :: cache_key() | term()}
  | {:put, key :: cache_key() | term(), value :: term()}

A cache action given to cache/1. Oaskit will use keys of type cache_key/0 when calling the cache.

cache_key()

@type cache_key() ::
  {:oaskit_cache, module(), responses? :: boolean(), variant :: term()}

The cache keys used by this module when calling cache/1.

Callbacks

cache(cache_action)

@callback cache(cache_action()) :: :ok | {:ok, term()} | :error

This callback is used to cache the built version of the OpenAPI specification, with JSV schemas turned into validators.

The callback will be called with :get to retrieve a cached build, in which case the callback should return {:ok, cached} or :error.
It will be called with {:put, value} to set the cache, in which case it must return :ok.

Caching is very important, otherwise the spec will be built for each request calling a controller that uses ValidateRequest. An efficient default implementation using :persistent_term is automatically generated. Override this callback if you need more control over the cache.

cache_variant()

@callback cache_variant() :: term()

This function is intended to change cache keys at runtime. The variant is any term used as the last element of a cache_key/0.

This is useful if you need to rebuild the OpenAPI specification and its validators at runtime, when the used schemas or even routes depend on current application state. For instance, if a schema for a given entity is fetched regularly from a remote source and changes over time.

The default implementation returns nil.

Stale cache entries are not purged automatically

If you return a new variant from this callback, cache entries stored with previous variants in the key are not automatically cleaned. You will need to take care of that. See cache/1 to implement a cache mechanism that you can control.

jsv_opts()

@callback jsv_opts() :: [JSV.build_opt()]

Returns the options that will be passed to JSV.build/2 when building the spec for the implementation module.

The default implementation delegates to Oaskit.default_jsv_opts/0.

spec()

@callback spec() :: map()

This function should return the OpenAPI specification for your application.

It can be returned as an %Elixir.OpenAPI{} struct, or a bare map with atoms or binary keys (for instance by reading from a JSON file at compile time).

The returned value will be normalized, any extra data not defined in the Oaskit.Spec... namespace will be lost.

Functions

cached(spec_module, cache_key, generator)

Retrieves a cached from the implementation module.

If the value is not in catche, the generator is called and the generated value is put in cache before being returned.

cast!(module)

Validates the given OpenAPI specification module returns a representation of the specification using structs such as Oaskit.Spec.OpenAPI, Oaskit.Spec.Response, etc.

default_jsv_opts()

Default options used for the JSV.build/2 function when building schemas:

[
  default_meta: JSV.default_meta(),
  formats: [Oaskit.JsonSchema.Formats | JSV.default_format_validator_modules()]
]

normalize_spec!(data)

Normalizes OpenAPI specification data.

Takes specification data (raw maps or structs) and normalizes it to a JSON-compatible version (with binary keys).

to_json!(module, opts \\ [])

@spec to_json!(module(), keyword() | map()) :: String.t()

Returns a JSON representation of the given OpenAPI specification module.

See Oaskit.SpecDumper.to_json!/2 for options.