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

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

@callback dump_extension(pair :: {String.t() | atom(), term()}) ::
  {String.t(), json_decoded() | extension_point()} | nil

Normalizes an extention key and value to a JSON encodable form.

Extensions are keys that are not known by Oaskit. They can be given to the Oaskit.Controller.operation/2 macro or found in a raw JSON specification.

This callback must return a pair with a string key and a JSON-encodable value.

It is also possible to return nil to ignore the pair. In that case, it will not be included in the JSON specification generated by mix openapi.dump and will not be available in the conn.private.oaskit.extensions data given to controllers.

Extension points given to operations declared in controllers are always normalized, see load_extension/1 for more information.

With use Oaskit, a default implementation is added and will attempt to preserve the original value to provide it to controllers without having to write a specific normalizer function.

Custom Serialization

If you override this callback, you should also override load_extension/1. The default implementation uses an internal struct to wrap the original value and preserve it through normalization. If you override only one of the two, you might lose this behavior or get unexpected results.

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

@callback load_extension(raw_pair :: {String.t(), term()}) :: {term(), term()} | nil

Loads an extension from its raw form and make it available in then conn.private.oaskit.extensions data given to controllers.

Extensions are keys that are not known by Oaskit. They can be given to the Oaskit.Controller.operation/2 macro or found in a raw JSON specification.

Note that due to the support for JSON based specifications, extensions are always normalized and then denormalized. It is necessary to declare this callback even for extension points that are only defined in controllers.

For instance:

operation :create_user,
  operation_id: "CreateUser",
  # ...
  custom_data: %MyApp.SomeStruct{}

In this case the dump_extension/1 callback will be called, and then the load_extension/1 callback will be called with the normalized pair.

With use Oaskit, a default implementation is added and will attempt to return the original declared in controller operations. This works well with the default implementation defined for dump_extension/1.

Custom Deserialization

If you override this callback, you should also override dump_extension/1. The default implementation uses an internal struct to wrap the original value and preserve it through normalization. If you override only one of the two, you might lose this behavior or get unexpected results.

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