GraphQL Document Generator

documentation generator for GraphQL API

Usage

the first argument receives a path to find the schema source, and second argument receives a path to export the markdown file.

$ npx gql-docgen [schema-source] [out-dir]

GrahqhQL endpoint

GraphQL endpoints are also supported.

$ npx gql-docgen https://your-gql-api/graphql ./out

With file system

if you want to use a local file or folder as a schema source, enter that path.

# folder
$ npx gql-docgen ./typeDefs ./out

# file
$ npx gql-docgen ./schema.gql ./out

Reserved tags

the informations can be expressed by attaching a reserved tag in the docstring of the schema file.

@req

The @req tag inside the docstring is shown as a block of code in the paragraph "Request"

type Query {
    """
    @req
    ```graphql
        query GetGuestCart($input: GetCartByGuestInput!) {
            guestCart(input: $input) {
                items {
                    _id
                    name
                    quantity
                }
                total
            }
        }
    ```
    """
    guestCart(input: GetCartByGuestInput!): GetCartPayload!
}

@res

The @res tag inside the docstring is shown as a block of code in the paragraph "Response"

type Query {
    """
    @res
    ```json
    {
        "data:: {
            "items": {
                ...
            }
        }
    }
    ```
    """
    guestCart(input: GetCartByGuestInput!): GetCartPayload!
}

@desc

The @desc tag adds a description just below the resolver name.

type Query {
    """
    @desc Gets the list of customer's cart items
    """
    guestCart(input: GetCartByGuestInput!): GetCartPayload!
}

Options

headers

when you fetch schemas from your graphql api, you might need to set your authorization key. if you attach headers option, you can.

$ npx gql-docgen https://your-gql-api/graphql ./out --header "Authorization=[your token]"

title

you can set your filename with title option.

# generated "commerce.mdx"
$ npx gql-docgen ./schema.graphql ./out --title Commerce

License

MIT