GraphqlMarkdown

Converts a JSON Graphql Schema to Markdown

Installation

Add graphql_markdown to your list of dependencies in mix.exs. It requires Elixir 1.15 or later:

def deps do
  [
    {:graphql_markdown, "~> 1.1"}
  ]
end

And run:

mix deps.get

Generate a single file called graphql_schema.md in the current dir:

mix graphql_gen_markdown -f ./schema.json

The full documentation is on HexDocs.

Quick Start

You can generate either single page with all the types or a multipage that will then generate separately Mutations, Queries, Enums etc, each in a different file.

Single page

When you run the following

mix graphql_gen_markdown -f ./schema.json

it will generate the following file in your current folder:

./graphql_schema.md

You can change the default title for the single page with -t option.

Multi pages

When you run the following

mix graphql_gen_markdown -f ./schema.json -m

it will generate the following files in your current folder:

./queries.md ./mutations.md ./subscriptions.md ./objects.md ./inputs.md ./enums.md ./scalars.md ./interfaces.md ./unions.md

Integrate with ExDoc and Absinthe

You can easily automate the process with ExDoc by adding the following to your mix.exs file:

defmodule Azeroth.MixProject do
  use Mix.Project

  # this is needed because the file are generated but if you run mix docs, Mix will check the existence of files first. so have to work around that
  @graphql_files [
    "guides/graphql/enums.md",
    "guides/graphql/inputs.md",
    "guides/graphql/interfaces.md",
    "guides/graphql/mutations.md",
    "guides/graphql/objects.md",
    "guides/graphql/queries.md",
    "guides/graphql/scalars.md",
    "guides/graphql/unions.md",
    "guides/graphql/subscriptions.md"
  ]
  ...

  defp aliases do
  [
    docs: [
      "absinthe.schema.json",
      "graphql_gen_markdown -f schema.json -o guides/graphql -m",
      "docs"
    ],...
  ]

Make sure the absinthe schema is specified or generated with that name. Or add to your config.exs:

config :absinthe, schema: YouApp.GraphQL.Schema

Using it as a library

GraphqlMarkdown.generate/1 takes the same options as the mix task and writes the files:

{:ok, files} = GraphqlMarkdown.generate(schema: "schema.json", output_dir: "guides", multi_page: true)

GraphqlMarkdown.render/1 returns the markdown in memory instead, keyed by filename:

{:ok, %{"graphql_schema.md" => markdown}} = GraphqlMarkdown.render(schema: "schema.json")

Documentation

Documentation is available on Hexdocs

Contributing

Fork it!
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Author

Emmanuel Pinault (@epinault)

License

GraphqlMarkdown is released under the MIT License. See the LICENSE.md file for further details.

Next Page → License