AsyncApiSpex (async_api_spex v0.1.0)

Copy Markdown View Source

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, 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, or write it to a file with mix async_api_spex.gen.

Summary

Functions

content_type()

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

encode!(document)

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

resolve(document)

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

to_map(document)

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

validate(document)

Validates a document, resolving it first.

Functions

content_type()

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

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

encode!(document)

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

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

See AsyncApiSpex.Encoder.encode!/1.

resolve(document)

@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(document)

@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(document)

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