# `Oaskit`
[🔗](https://github.com/lud/oaskit/blob/v0.13.1/lib/oaskit.ex#L1)

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

```elixir
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
```

# `cache_action`

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

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

# `cache_key`

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

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

# `extension_point`

```elixir
@opaque extension_point()
```

# `json_decoded`

```elixir
@type json_decoded() ::
  %{optional(binary()) => json_decoded()}
  | [json_decoded()]
  | String.t()
  | number()
  | boolean()
  | nil
```

# `cache`

```elixir
@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`

```elixir
@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 `t: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 {: .warning}
>
> 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 `c:cache/1` to implement a cache mechanism that you
> can control.

# `dump_extension`

```elixir
@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 `c: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 `c: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.

# `jsv_opts`

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

# `load_extension`

```elixir
@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 `c:dump_extension/1` callback will be called, and then the
`c: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 `c:dump_extension/1`.

### Custom Deserialization

If you override this callback, you should also override `c: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.

# `spec`

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

# `cached`

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!`

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()],
  atoms: true
]
```

# `normalize_spec!`

Normalizes OpenAPI specification data.

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

# `to_json!`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*