# `AsyncApiSpex`
[🔗](https://github.com/jamescarr/ankusa/blob/async_api_spex-v0.2.0/packages/async_api_spex/lib/async_api_spex.ex#L1)

Declarative AsyncAPI 3.0 documents for Elixir applications.

Build an `AsyncApiSpex.Document` from structs, optionally declaring reusable
schemas with `use AsyncApiSpex.Schema` and messages with
`use AsyncApiSpex.Message`, or decorate the structs and publishing modules an
application already has: `use AsyncApiSpex.Schema, fields: [...]` on a struct,
`use AsyncApiSpex.Channel` on a module that publishes to a topic, and
`use AsyncApiSpex.Spec` to assemble the document from them. Then:

  * `resolve/1` extracts those modules into `components` and replaces their
    uses with references;
  * `to_map/1` produces a JSON-encodable map;
  * `encode!/1` produces JSON;
  * `validate/1` checks the document and reports errors by JSON path.

Serve a document from a Plug application with `AsyncApiSpex.Plug.RenderSpec`,
browse it as an HTML page with `AsyncApiSpex.Plug.Viewer`, or write it to a
file with `mix async_api_spex.gen`.

# `content_type`

```elixir
@spec content_type() :: String.t()
```

Returns the media type of an AsyncAPI document, `"application/asyncapi+json"`.

# `encode!`

```elixir
@spec encode!(AsyncApiSpex.Document.t()) :: binary()
```

Encodes a document as a JSON string. Resolves it first.

See `AsyncApiSpex.Encoder.encode!/1`.

# `resolve`

```elixir
@spec resolve(AsyncApiSpex.Document.t()) :: AsyncApiSpex.Document.t()
```

Extracts schema and message modules into components, returning a new document.

See `AsyncApiSpex.Resolver.resolve/1`. Idempotent.

# `to_map`

```elixir
@spec to_map(AsyncApiSpex.Document.t()) :: map()
```

Encodes a document as a JSON-encodable map. Resolves it first.

See `AsyncApiSpex.Encoder.to_map/1`.

# `validate`

```elixir
@spec validate(AsyncApiSpex.Document.t()) :: :ok | {:error, [String.t()]}
```

Validates a document, resolving it first.

Returns `:ok` or `{:error, messages}`, where each message names the JSON path
of the problem. See `AsyncApiSpex.Validator.validate/1`.

---

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