2fd/graphdoc

Static page generator for documenting GraphQL Schema

graphdoc's Issues

I need help about JWT auth

Hello.
I need help, so I've created an issue.

We are going to use graphdoc to document the project that has been completed.
However, our project is now designed to be accessible to graphql even though it must pass JWT certification.
So if you want to document using graphdoc, you have to send Authorization to header.
I would appreciate it if you can help me.

I would like to apply it as shown below.

I would appreciate your reply anytime.

Thank you.

  {
        "name": "project",
        // [...]
        "graphdoc": {
            "endpoint": "http://localhost:8080/graphql",
            "header":{"Authorization":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"}
            "output": "./doc/schema",
        }
    }

graphdoc -e http://localhost:8080/graphql -o ./doc/schema

[request] support GraphQL IDL

graphdoc -s schema.graphql

# schema.graphql
schema {
  query: Query
}
type Query {
  hello: String
}

Compress HTML output

Missing descriptions for complex input type fields

When custom input types are defined (an OperationInput that is a GraphQLInputObjectType), the descriptions of the subfields are not available in the generated docs.

This is a little frustrating to get to even in the GraphiQL, but impossible in graphdoc.

An example, from https://2fd.github.io/graphdoc/github/addprojectcardinput.doc.html . In GraphiQL, I have to go to AddProjectCardInput and then click on projectColumnId to see its description. In graphdoc I can't see this description available anywhere. Frankly, I would like to have it documented already on the level shown at the screenshot, without the extra click.

(Left: github's GraphiQL, right - graphdoc demo)

new plugin: google analytics

Add option flag for plugin configuration

Support String literal descriptions

Good day. Thanks for your work on this project. It's incredibly useful.

As per https://github.com/graphql/graphql-js/blob/master/src/utilities/extendSchema.js#L47, descriptions defined within an IDL (SDL) are defined as String Literals. I'm currently seeing the following error.

 ✗ Syntax Error GraphQL (5:1) Unexpected String "My description"

4:
5: "My description"
   ^
6: type QueryRoot {

Thanks for your time.

Status of this project

I see the last commit was 8 months ago but there are PRs that haven't been commented by a maintainer for a year now. I'm afraid to ask, is this project maintained any more? This project is great but there are certain things that could be improved and fixed. Would be sad if this project went inactive.

Potential License Issues

Hi,

Sorry if this issue is improperly formatted, I didn't see any defaults or a CONTRIBUTING.md or something of the sort.

Just wanted to point out the Licenses from salesforce-ux. I'm not great with Licenses, but I just wanted to point out that you may want to use a different font / design kit. The tool is super useful, just don't want it to come down for an easily resolvable issue.

license.md

I didn't read through the entirety of the License, but it seems as this repo is MIT whereas Salesforce requires your repository to be BSD-3.

license-font.md

From Section 1:

use the Font solely to create applications with the Salesforce Lightning Design System that run in Salesforce or on a Salesforce platform

From Section 2:

To the extent your Application contains copyright notices,
together with all other copyright notices included with each Application, You
will include the following copyright notice: “The Salesforce Sans Font is used
under license from salesforce.com, inc. Copyright 2015 Salesforce.com, Inc.”
You may not modify, adapt, translate, reverse engineer, decompile,
disassemble, or create derivative works based on the Font. You must include
the Font in an Application in a manner that does not allow a user to access
the Font outside of the Application. You will not use the Font on a
standalone basis and will only use the Font as part of the Salesforce
Lightning Design System.

how to generate doc from a folder

I would like to generate graphQL docs from a source folder which has multiple sub-folders where files with .graphqls suffix. Is there a way to do it? thanks.

JSON Schema input crashes on latest version

Hello,

I've created a schema.json using the introspection query shown by the documentation. However, when running the script to create the documentation page, I hit an issue right away:

Cannot read property '__schema' of undefined

A closer look at lib/schema-loader/json.js shows this:

    try {
        var schemaPath = path_1.resolve(options.schemaFile);
        var introspection = require(schemaPath);
        return Promise.resolve(introspection.data.__schema);
    }

Why is there an expectation of a data field in the introspected schema.json file? I am able to generate a documentation page by removing the data field. But, I would like to know why the data field was put in the first place. I'm not sure if there are grave consequences to doing this. If this is an uncaught issue, I would be happy to open a PR 😄

Thanks!

No document for mutation with multiple arguments

type Mutation {
  # Register new user, need to remove Authorization and RefreshToken headers
  register(
    # User firstname
    firstname: String!
    # User lastname
    lastname: String!
    # User email address
    email: String!
    # User password
    password: String!
  ): User!
  # Login to system, need to remove Authorization and RefreshToken headers
  login(
    # User email address
    email: String!
    # User password
    password: String!
  ): LoginResponse
}

But got this:

So how can I make the document display for arguments?

[feature request] Search for Query, Mutation fields

Hi 👋

I would like to be able to use the filter/search bar to find fields in Query/Mutation, the user experience would be similar to GraphiQL explorer.

Thoughts?

Hide or Remove certain mutations / queries?

I have been using this package internally for my documentation for a while now (usually just the static generation of files) and I love it. However I am hoping to make a large portion of my API public, I have already gone through and setup my actual routes to not work for people other than myself, but is it possible to easily flag a schema so that the document generation ignores it?

I basically am looking for a way to ignore either a query, mutation, type / input from being added to the generated docs, I can delete the files but then I have to go and edit every single files nav and remove it there also.

Set GraphiQL url from cli

https://github.com/2fd/graphdoc/blob/master/example.pokemon.json#L16

I want to set GraphiQL url when using CLI.

example:

graphdoc -e https://graphql-pokemon.now.sh -o ./doc/schema --url https://graphql-pokemon.now.sh

Is there a any solution?

Version 3 roadmap

Version 3

• move project to @graphdoc organization
• move package to @graphdoc namespace in npm
• custom domain https://graphdoc.dev (?)
• dependency changes
  • use oclif for cli
  • use react for templating
• re-struct the project as a mono-repo and separate functionalities
  • @graphdoc/cli: cli implementation
  • @graphdoc/components: react components to render each documentation section
  • @graphdoc/source-{http,json,...}: logic to download/load the introspection query
  • @graphdoc/output-{html,md,ts,flow,...}: logic to generate output
• integration with other services and documentation tools
  • docusaurus
  • apollo (?)
  • gatsbyjs (?)
• use docusaurus to generate documentation

dependency on insecure abandoned module

Hi,

This library has a dependency on the module slug, which is currently subject to a node security advisory. Looking at the project's Github repo, it does not appear that the maintainer is still around-- their last activity on the repo was in April of 2015, nearly 3 years ago.

Would it be possible to switch to a different dependency? Here are a couple alternatives based on some preliminary research:

• https://www.npmjs.com/package/limax
• https://www.npmjs.com/package/mollusc

Thanks!

support for extending types

It would be nice to support the extend keyword for graphql schema type definitions, it currently doesn't seem to work for graphdoc.

example:
http://dev.apollodata.com/tools/graphql-tools/generate-schema.html#extend-types

apparently it's a [yet] undocumented feature:
graphql/graphql-js#166

simple example/test case:

# Query seems to have at least one field defined, not sure if that will be the case in the future
type Query {
  _dummy: Boolean
}

extend type Query {
  getTask: String
}

schema {
  query: Query
}

Add output to the footer of template using plugins

Does not support GraphQL comments

I have a schema.graphql. The tool does not like the comment and gave the following error

✗ Syntax Error GraphQL (6:1) Unexpected String

5:
6: """The available actions for this resource."""
   ^
7: type actions {

Cannot find module 'striptags'

2.1.0 fails to run, printing above error.

Also, can you make a changelog or add notes to the Releases page? v1.2.0 -> v2.0.0 implies a breaking change, but I have no idea what that might be.

Cannot install via npm

When trying to install graphdoc with npm, I get the following error:

npm WARN package.json [email protected] No license field.
npm ERR! 404 Not Found
npm ERR! 404 
npm ERR! 404 '2fd/command' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it
npm ERR! 404 It was specified as a dependency of '@2fd/graphdoc'
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, or http url, or git url.

npm ERR! System Linux 4.11.0-2-amd64
npm ERR! command "/usr/bin/nodejs" "/usr/bin/npm" "install" "@2fd/graphdoc"
npm ERR! cwd /home/davux/xxx
npm ERR! node -v v4.8.4
npm ERR! npm -v 1.4.21
npm ERR! code E404

Is there anything I'm missing?

Unable to generate doc when secure server uses self signed certificate

Trying to generate a documentation for graphql server which has a self signed certificate.
Terminal output:

$ graphdoc --verbose -e https://..../graphql -o . -x "Authorization: Bearer xGe2tZfpq4...lipMrCh" --force
 ✗ self signed certificate
Error: self signed certificate
    at TLSSocket.<anonymous> (_tls_wrap.js:1098:38)
    at emitNone (events.js:105:13)
    at TLSSocket.emit (events.js:207:7)
    at TLSSocket._finishInit (_tls_wrap.js:628:8)
    at TLSWrap.ssl.onhandshakedone (_tls_wrap.js:458:38)

Is there an option to enable fetching a schema from such GraphQL API server?

Is it possible to use this module programmatically as a dependency?

I'm thinking something like:

const graphdoc = require('@2fd/graphdoc');

graphdoc(OUTPUT_PATH, CONFIG_OBJ);

Even loading the module in NPM using the method above, let alone using it, is causing errors for me.

Print relative paths on console

Make template responsive

[Audit] Regular Expression Denial of Service

┌───────────────────────────────────────────────────────
│ Moderate: Regular Expression Denial of Service
├───────────────────────────────────────────────────────
│ Package : marked
├───────────────────────────────────────────────────────
│ Patched in: >=0.6.2
├───────────────────────────────────────────────────────
│ Dependency of: @2fd/graphdoc [dev]
├───────────────────────────────────────────────────────
│ Path: @2fd/graphdoc > marked
├───────────────────────────────────────────────────────
│ More info : https://npmjs.com/advisories/812
└───────────────────────────────────────────────────────

Angular CLI: 7.3.8
Node: 10.15.3
OS: linux x64
Angular: 7.2.13
... animations, common, compiler, compiler-cli, core, forms
... language-service, platform-browser, platform-browser-dynamic
... router

Package Version

@angular-devkit/architect 0.13.8
@angular-devkit/build-angular 0.13.8
@angular-devkit/build-ng-packagr 0.13.8
@angular-devkit/build-optimizer 0.13.8
@angular-devkit/build-webpack 0.13.8
@angular-devkit/core 7.3.8
@angular-devkit/schematics 7.3.8
@angular/cdk 7.3.7
@angular/cli 7.3.8
@ngtools/json-schema 1.1.0
@ngtools/webpack 7.3.8
@schematics/angular 7.3.8
@schematics/update 0.13.8
ng-packagr 5.1.0
rxjs 6.4.0
typescript 3.2.4
webpack 4.29.0

Document schema that uses graphql modules

Right now you can't document a file that uses graphql modules (via a package like graphql-import). If this was added is this something that would be useful to most users? It would be a simple case of running the graphql-import function on the schema before it is build in the idl.ts loader. More than happy to submit a PR for this or am I better off forking and doing this for my own use?

Option to skip built-in types

Is it possible to skip the built-in types like scalars and all the underscored stuff like __DirectiveLocation?

Apply Markdown processing to ALL instances of descriptions

I make heavy use of Markdown in my GraphQL documentation. Some tools get this right, while others have odd gaps in support. For example, even GraphiQL leaves some Markdown unprocessed.

It would be nice if all descriptions were processed with Markdown to generate HTML. If HTML output isn't appropriate, then do Markdown → HTML generation, followed by stripping HTML tags from the output.

This would provide a cleaner experience with the text.

Problem after switching to Apollo GraphQL server express

Previously was running my schema with express-graphql and graphdoc was working fine running against my dev GraphQL endpoint. Recently decided to switch to graphql-server-express (Apollo server), and now the same graphdoc command results in:

[405] Method Not Allowed on http://localhost:5000/graphql

Is this a known thing with Apollo server?

It works if I manually generate a schema.json by querying IntrospectionQuery, then running graphdoc against that.

Add test

The input objects not properly identan

add multiple endpoint configurations

Unexpected schema definition on "undefined"

Hi when running the doc on a modularized schema, Im getting Unexpected schema definition on "undefined".

graphdoc -s ./src/schema/index.js -o ./doc/schema

index.js is transpile using babel via rollup

import Post from './models/Post';
import User from './models/User';
import resolvers from './resolvers'

const RootQuery = `
  type RootQuery {
    posts: [Post]
    post (id: Int!): Post
    users: [User]
    user: User
  }
`;

const SchemaDefinition = `      
  schema {
    query: RootQuery
  }
`;

export default makeExecutableSchema({
  typeDefs: [
    SchemaDefinition, RootQuery, Post, User
  ],  
  resolvers
});

node v8.11.2
npm 6.4.1

Thanks!

Update Lightning Design System

Lacking build instructions

Hi

I'm trying to add the ability to link directly to a field over here, but I can't test my changes because I don't know how to build the project. Can somebody in the know outline the steps here?

Add plugin that unifies the default content

Currently the default configuration includes multiple plugins

            [
                'graphdoc/navigation.schema',
                'graphdoc/navigation.scalar',
                'graphdoc/navigation.enum',
                'graphdoc/navigation.interface',
                'graphdoc/navigation.union',
                'graphdoc/navigation.object',
                'graphdoc/navigation.input',
                'graphdoc/navigation.directive',
                'graphdoc/document.schema',
            ]

It should additionally be available as a single plugin

            [ 'graphdoc' ]
            // or
            [ 'graphdoc/default' ]

new plugin: dependencies type graph

Example: http://mbostock.github.io/d3/talk/20111116/bundle.html

HTTP Status Code 401 (Unauthorized)

I got an error when I use it against our live GraphQL end point. What's wrong?

✗ Unexpected HTTP Status Code 401 (Unauthorized) from: https://xxx/api/graphql

I assume it is because the header AUTH-TOKEN is missing so I tried these without success.

--header ["AUTH-TOKEN": "xxx"]
--header ["AUTH-TOKEN=xxx"]
--header ["Authorization: Token xxx"]

how to put * to execute whole '.gql' files from a folder in scripts of package.json

i have used scripts body as "scripts": { "start_docs":"npm run graphdoc", "graphdoc": "graphdoc -s schema/*.gql -f -o ./support/reports/graphdoc;exit 0" } While I put multiple '.gql' using * from schema folder, then error like /Documents/graphql_new/stature-gqdss/node_modules/@2fd/command/lib/command/params.js:104 throw new Error('Unexpected param: ' + param); ^

Error: Unexpected param: schema/basic-profile-schema.gql at NoParams.parse (/home/jamsheerali/Documents/graphql_new/stature-gqdss/node_modules/@2fd/command/lib/command/params.js:104:15)

Customize CSS for code generation

Looks like there's an assets directory that is generated for the output, but it isn't part of the template for editing. I'm having to use nasty !important statements to override.

Can this be part of the template?

cannot use many config options from json config using -c

When you specify plugins in package.json, ignores them completely due to this line https://github.com/2fd/graphdoc/blob/master/lib/command.ts#L197

For example. If I run yarn graphdoc -c file.json, where file.json is

{
    "graphdoc": {
	    "plugins": [
	        "foo.js"
	    ]
    }
}

then before L197:

packageJSON = {
    "graphdoc": {
	    "plugins": [
	        "foo.js"
	    ]
    }
}

input.flags = {
    "configFile": "/tmp/graphql-docs.json",
    "headers": [],
    "queries": [],
    "plugins": [],
    "data": {},
    "force": true,
    "verbose": true,
    "version": false,
    "help": false
}

note how there are already properties set on input.flags - these override the values set in the provided config when using Object.assign.

the solution is make sure that input.flags is not given default values, or use a custom merge function that only copies across values that have been set.

Remove 'INPUT OBJECTS' and 'DIRECTIVES' category

Is there anyway for me to customize the output which will exclude 'INPUT OBJECTS' and 'DIRECTIVES' category?

Improve description for not documented parameters

Change [NULL] for [NOT DOCUMENTED]

Unexpected HTTP Status Code 403 (Forbidden) in spite of no authentication required.

Hello,

I have a graphql endpoint which requires no authentication.

I'm able to browse the URL from chrome / firefox without any issues or having to enter any login details but when i use the command below it errors out as shown.

graphdoc -e http://localhost:8000/graphql -o . /doc/schema
✗ Unexpected HTTP Status Code 403 (Forbidden) from: http://localhost:8000/graphql

What can i look into here and is this an issue someone has run into prior ?

Thanks for your help.

Default parameter value is lost

Given:

type Query {
    foo(
        bar: Int = 1
    ): Foo!
}

The generated doc will show:

type Query {
    foo(
        bar: Int
    ): Foo!
}

The default 1 value isn't displayed anymore.

More control over source code generation

Would love to be able to exclude documentation for the types in the output (i.e., show the GraphQL models without a bunch of poorly-wrapped plain text documentation mixed in).

"GET /docs/scripts/toggle-navigation.js HTTP/1.1" 404

hi,

when i generate the documentation with the latest stable version of the library i get that 404 on my server at every page load.

Improve templates partials

Currently only possible to create template from 4 files (index.mustache, main.mustache, nav.mustache and footer.mustache) that are injected as partials (index, main, nav and footer respectively) this limits the possibilities of generating complex templates properly structured.

it should be possible to structure a template as the designer deems necessary and that these are injected automatically as partials