Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/podium/graphql_markdown
A plugin for ex_doc to autogenerate Grapqhl documentation into ex_doc
https://github.com/podium/graphql_markdown
documentation elixir elixir-lang graphql
Last synced: about 2 months ago
JSON representation
A plugin for ex_doc to autogenerate Grapqhl documentation into ex_doc
- Host: GitHub
- URL: https://github.com/podium/graphql_markdown
- Owner: podium
- License: mit
- Created: 2021-09-17T17:09:42.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-14T14:37:29.000Z (3 months ago)
- Last Synced: 2024-10-29T08:44:51.837Z (2 months ago)
- Topics: documentation, elixir, elixir-lang, graphql
- Language: Elixir
- Homepage: https://hexdocs.pm/graphql_mardown
- Size: 92.8 KB
- Stars: 2
- Watchers: 12
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# GraphqlMarkdown
Converts a JSON Graphql Schema to Markdown
## Installation
If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `graphql_markdown` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:graphql_markdown, "~> 0.4.3"}
]
end
```
And run:
```shell
mix deps.get
```
Generate a single file called `graphql_schema.md` in the current dir:
```shell
mix graphql_gen_markdown -f ./schema.json
```
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/graphql_markdown](https://hexdocs.pm/graphql_markdown).
## 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
```shell
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
```shell
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:
```elixir
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:
```elixir
config :absinthe, schema: YouApp.GraphQL.Schema
```
## Documentation
Documentation is [available on Hexdocs](https://hexdocs.pm/graphql_markdown/)
## Contributing
1. [Fork it!](http://github.com/podium/graphql_markdown/fork)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## Author
Emmanuel Pinault (@epinault)
## License
GraphqlMarkdown is released under the MIT License. See the [LICENSE.md](LICENSE.md) file for further details.