graphql-api-page-generator v1.3.1

GraphQL API Page Generator

A npm package and command line tool for generating an API page from a GraphQL schema that is intended for public display.

Directives can be used for extra information about the schema.

HTML and Markdown descriptions are supported!

Installation

To install as NodeJS npm package:

npm install graphql-api-page-generator

To install as command line tool:

npm install -g graphql-api-page-generator

To see all the options and verify installation:

gqlapi --help

Usage - NodeJS

Example 1: Generating an API page from GraphQL schema (text)

Examples of real schema files can be found under /examples folder. It includes one example of a schema that is using the features of this generator, and the schema of GitHub's API, which was obtained via introspection (on April 24th 2018).

const generator = require('graphql-api-page-generator')

// GraphQL schema as text. Good chances you will actually read this from a file.
let schema = `
type Student {
    name: String @length(min: 2, max: 5)
    age: Int @range(max: 120)
}
type Query {
    students: [Student] @length(max: 1000)
}
`

generator.buildAPIPage(schema, "Students API", "An API to get all students.")
    .then(html => /* do something with the HTML text */)
    .catch(reason => /* handle failure */);

Example 2: Generating an API page from a live GraphQL server (via introspection)

const generator = require('graphql-api-page-generator')

let query = graphql.introspectionQuery;
let introspectionResult = /* response body for a POST request to the server with 'query' as a body */

let schema=graphql.buildClientSchema(introspectionResult.data);
apiPageBuilder.buildAPIPage(schema, "Students API", "An API to get all students.")
    .then(html => /* do something with the HTML text */)
    .catch(reason => /* handle failure */);
});

The buildApiPage has an additional parameter headPart, in which HTML parts for the head tag can be added in order to customize the result.

Usage - Command line

Generating an API page from a schema file

GraphQL API Page Generator supports the GraphQL SDL of graphql.js

$> gqlapi  from-file --help
gqlapi from-file <outputfile> <path> <apiname> [description]

Writes API as HTML from a file to the given output file

Positionals:
outputfile   name (and path) of file to which the API HTML will be saved
                                                [required] [default: "API.html"]
path         the path to the graphql schema file (in graphql.js SDL format)
                                                            [string] [required]
apiname      name of the API                               [string] [required]
description  description of the API                                   [string]

Options:
--version  Show version number                                       [boolean]
-h, --head-part  Path to a file with text (utf-8) that will be inserted at the
               end of the `head` tag in the output html. This can be used to
               provide your own CSS (`link`/`style` tag), your own
               javascript code (`script` tag) or anything else. Since this
               tag is inserted at the end of the `head` tag, it may override
               anything that was generated by the tool. THIS TEXT WILL NOT
               BE SANITIZED as it is intended for use only by the script
               host, so don't receive this as input from external users (or
               sanitize first).
--help     Show help                                                 [boolean]

for example:

gqlapi from-file out.html examples/schema.graphql "Example API" "This is a description of a great API" -h examples/example.html

Generating an API page from a live GraphQL server (via introspection)

GraphQL API Page Generator can create an API page for any live GraphQL server by sending introspection query.

$> gqlapi from-url --help
gqlapi from-url <outputfile> <url> <apiname> [description]

Writes API as HTML from a live GraphQL server (via introspection) to the given
output file

Positionals:
outputfile   name (and path) of file to which the API HTML will be saved
                                                [required] [default: "API.html"]
url          the path to the graphql file or the URL to the GraphQL service
                                                            [string] [required]
apiname      name of the API                               [string] [required]
description  description of the API                                   [string]

Options:
--version  Show version number                                       [boolean]
-h, --head-part  Path to a file with text (utf-8) that will be inserted at the
               end of the `head` tag in the output html. This can be used to
               provide your own CSS (`link`/`style` tag), your own
               javascript code (`script` tag) or anything else. Since this
               tag is inserted at the end of the `head` tag, it may override
               anything that was generated by the tool. THIS TEXT WILL NOT
               BE SANITIZED as it is intended for use only by the script
               host, so don't receive this as input from external users (or
               sanitize first).
--help     Show help                                                 [boolean]

For example:

gqlapi from-url out.html "http://graphql.communitygraph.org/graphql/" "Example API" "This is a description of a great API"

HTML & Markdown description support

The description will be rendered as Markdown (with markdown-it).

The description of every item kind may contain HTML tags that will be embedded into the generated HTML file. Note, however, that the HTML is sanitized for security purpose. For a complete list of allowed tags and attributes, see the sanitize-html docs.

Supported directives

GraphQL API Page Generator is supporting directives that allows the schema publisher to provide extra information about the API behavior.

The @deprecated directive

directive @deprecated(reason: String) on 
    SCALAR|OBJECT|FIELD_DEFINITION|ARGUMENT_DEFINITION|
    INTERFACE|UNION|ENUM|ENUM_VALUE|INPUT_OBJECT|
    INPUT_FIELD_DEFINITION

Used to indicate deprecation, with an optional reason. Can be used on type (any kind), field, argument or enum value.

*Note: some GraphQL libraries declare deprecated to be used on less schema parts (only field definition for example). Although this deprecated message will not show up in introspection (and therefore neither in GraphiQL, you can still declare it in the schema file and GraphQL API Page Generator will still process this directive wherever it appears, given the schema file. However, this directive will not appear if schema is obtained via introspection.*

Example:

type Student @deprecated (reason: "University is closing") {
    "The name of the student"
    name: String! @deprecated(reason: "Use 'full name' instead") 
    "Full name"
    fullName: String 
    "The average grade"
    grade(onlyLastYear: Float @deprecated(reason: "not supported anymore")): Int
}

Result:

The @range directive

directive @range(min: Float = -∞, max: Float = ∞, maxPrecision: Float) on 
    FIELD_DEFINITION|ARGUMENT_DEFINITION|INPUT_FIELD_DEFINITION|SCALAR

Used to describe the valid range of a numerical field or argument. If min is not provided, it is considered to be -∞ , if max is not defined it is considered to be ∞. Both min and max are regarded as inclusive.

The maximal precision is a number that represents the smallest step acceptable. Typically it will be in a form such as 0.01

*Note: some GraphQL libraries do not support custom directives. GraphQL API Page Generator will still process this directive wherever it appears, given the schema file. However, this directive will not appear if schema is obtained via introspection.*

Example:

type Student {
    "The name of the student"
    friends(
        "get a limited number of friends"
        first: Int! @range(min: 1, maxPrecision: 0.1)
    ): String!
    "The average grade"
    grade: Int @range(min: 0, max: 100)
}

Result:

The @length directive

directive @length(min: Float = 0, max: Float = ∞, level: Int = 1) on 
    FIELD_DEFINITION|ARGUMENT_DEFINITION|INPUT_FIELD_DEFINITION|SCALAR

Used to describe the valid length of field or argument that are array or string. If min is not provided, it is considered to be 0 , if max is not defined it is considered to be ∞. Both min and max are regarded as inclusive.

level is used for nested objects tha has length. For example, a field of type [[int]], in which we would want to describe length limit of outer and inner arrays, or field of type [string] in which we would like to describe the length of both the array and the string. The level is ordering the length definitions from outer to inner, e.g. in this definition:

nameLists: [[string]] 
    @length(max: 3, level:1) 
    @length(min: 1, max: 8, level:2) 
    @length(max:5, level: 3)

we have an array that holds up to 3 arrays, each one with 1 to 8 strings in length of up to 5 characters. If level is not defined it is considered to be 1. @length directive with equal level are sorted according to order of appearance.

*Note: some GraphQL libraries do not support custom directives. GraphQL API Page Generator will still process this directive wherever it appears, given the schema file. However, this directive will not appear if schema is obtained via introspection.*

Example:

type Query {
    "get all students"
    students(
        "only those that contains this string"
        contains: String @length(min: 1, max: 5)
    ): [Student] @length
    "Get all classes"
    classes: [Class] @length(min: 0, max: 100)
    otherNames: [String] 
        @length(max:8, level: 1) 
        @length(min: 2, max: 20, level: 2)
}

Result:

The @mask directive

directive @mask(regExp: String!) on 
    FIELD_DEFINITION|ARGUMENT_DEFINITION|INPUT_FIELD_DEFINITION|SCALAR

Used to describe the valid values of a string field or argument.

*Note: some GraphQL libraries do not support custom directives. GraphQL API Page Generator will still process this directive wherever it appears, given the schema file. However, this directive will not appear if schema is obtained via introspection.*

Example:

type Student {
    "Identifier of the student as supplied by the school"
    id: String @mask(regExp: "^stud[0-9]{1,10}$")
}

Result:

Customizing

The generated result can be customized using the headPart argument (on NodeJS) or the -h flag.

The content of the string passed in headPart ot he content of the file pointed after the -h flag will be inserted at the end of the head tag in the output html. This canbe used to provide your own CSS (link/style tag), your own javascript code (script tag) or anything else. Since this tag is inserted at the end of the head tag, it may override anything that was generated by the tool.

This text will not be sanitized as it is intended for use only by the script host, so don't receive this as input from external users (or sanitize first).

For example, we run this command:

gqlapi from-file out.html examples/schema.graphql "Example API" "This is a description of a great API" -h examples/example.html 

The content of example.html will be added to the output file in the end of the head file. This example file will change the header fonts and the section header fonts and will change the main color to blue