GraphqlMarkdown (Graphql Markdown v1.2.0)

Copy Markdown View Source

Converts a GraphQL JSON schema to a markdown format

Summary

Types

change()

A file that check/1 found out of date: it differs from the rendered markdown (:changed) or does not exist (:missing).

error()
pages()

Rendered pages, keyed by filename (for example "graphql_schema.md").

Functions

check(options)

Renders the markdown and compares it with the files in :output_dir (default: the current directory), without writing anything.

generate(options)

Renders the markdown and writes it into :output_dir (default: the current directory). Returns the list of files written.

render(options)

Renders the markdown in memory and returns it keyed by filename.

Types

change()

@type change() :: {Path.t(), :changed | :missing}

A file that check/1 found out of date: it differs from the rendered markdown (:changed) or does not exist (:missing).

error()

@type error() ::
  :missing_schema
  | :invalid_schema
  | :absinthe_not_available
  | {:not_a_schema, module()}
  | {:introspection_failed, term()}
  | {:invalid_depth, term()}
  | {:invalid_link_ext, term()}
  | File.posix()
  | Jason.DecodeError.t()

pages()

@type pages() :: %{required(String.t()) => String.t()}

Rendered pages, keyed by filename (for example "graphql_schema.md").

Functions

check(options)

@spec check(keyword()) :: :ok | {:error, {:outdated, [change()]} | error()}

Renders the markdown and compares it with the files in :output_dir (default: the current directory), without writing anything.

Returns :ok when every file is up to date, or {:error, {:outdated, changes}} listing the files that differ or are missing, sorted by filename. Use it in CI to make sure the committed documentation matches the schema.

Accepts the same options as generate/1.

generate(options)

@spec generate(keyword()) :: {:ok, [Path.t()]} | {:error, error()}

Renders the markdown and writes it into :output_dir (default: the current directory). Returns the list of files written.

Files are written only after every page has been rendered, so a failure never leaves a partially written file behind.

render(options)

@spec render(keyword()) :: {:ok, pages()} | {:error, error()}

Renders the markdown in memory and returns it keyed by filename.

Nothing is written to disk. Use this to embed the generator in your own pipeline or to inspect the output in tests.

Accepts the same options as generate/1 except :output_dir.

Options

The schema comes from exactly one of:

  • :schema - path to an introspection JSON file, as written by mix absinthe.schema.json or any GraphQL tooling
  • :schema_module - an Absinthe schema module, introspected in-process. Requires absinthe in your dependencies

Rendering options:

  • :multi_page - one file per section instead of a single page
  • :title - title of the single page. Default: "Graphql Schema"
  • :no_toc - leave the table of contents out of the single page
  • :depth - how many nested levels the example operations select, counting the operation's own selection set. Default: 2. Must be a positive integer, otherwise {:error, {:invalid_depth, value}} is returned
  • :link_ext - extension of the links between multi-page files: :html (default, for ExDoc), :md (GitHub, MkDocs) or :none (clean URLs, Docusaurus). Anything else returns {:error, {:invalid_link_ext, value}}
  • :front_matter - start every page with a YAML block holding its title
  • :backlinks - end every object, input, enum, interface and union entry with the operations that return it (Returned by) and the types and operations that use it in a field or argument (Used by)