{"id":13515274,"url":"https://github.com/wayfair/dociql","last_synced_at":"2025-03-31T04:36:50.982Z","repository":{"id":38375225,"uuid":"169739821","full_name":"wayfair/dociql","owner":"wayfair","description":"A beautiful static documentation generator for GraphQL ","archived":false,"fork":true,"pushed_at":"2025-02-14T22:57:20.000Z","size":3087,"stargazers_count":363,"open_issues_count":19,"forks_count":97,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-27T10:46:52.540Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"https://github.com/wayfair/dociql","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"sourcey/spectacle","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wayfair.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-02-08T13:34:11.000Z","updated_at":"2025-03-21T05:13:59.000Z","dependencies_parsed_at":"2023-01-24T22:15:11.726Z","dependency_job_id":"8882c523-7f25-45fe-912d-c3083f22dca4","html_url":"https://github.com/wayfair/dociql","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair%2Fdociql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair%2Fdociql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair%2Fdociql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair%2Fdociql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wayfair","download_url":"https://codeload.github.com/wayfair/dociql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246418658,"owners_count":20773934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-08-01T05:01:08.699Z","updated_at":"2025-03-31T04:36:45.968Z","avatar_url":"https://github.com/wayfair.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# DociQL\n\n[![npm][npm]][npm-url]\n[![downloads][npm-downloads]][npm-url]\n[![builds][builds]][builds-url]\n[![coverage][cover]][cover-url]\n[![Quality Gate Status][sonar]](sonar-url)\n\n\u003e A nice fork of [Spectacle](http://sourcey.com/spectacle)\n\nDociQL generates beautiful static HTML5 documentation from a [GraphQL](https://graphql.org) endpoint using the introspection query.\n\nThe goal of DociQL is help you \"save time and look good\" by providing an extensible platform for auto generating your API documentation. The default layout is a three column single page, similar to those\nemployed by [Stripe](https://stripe.com/docs/api) and [Intercom](https://developers.intercom.com/reference).\n\nSee a demo of DociQL in action here: [https://wayfair.github.io/dociql/](https://wayfair.github.io/dociql/)\n\n---\n\n![Demo Screenshot](screenshot.png)\n\n---\n\n## Features\n\n* Uses the introspection query to fetch a schema of GraphQL and generates documentation on the fly.\n* Generates an example request and response with \"Try it now\" links.\n* Allows the user to define use cases and group them by domain.\n* **Highly configurable**: Easily configurable Handlebars templates and SCSS styles so you can add your own design and flavour without going bald. See [Custom Builds](#custom-builds).\n* **Markdown support**: Render markdown written in any of your API descriptions.\n* **Clean, responsive design**: Responsive HTML5 and CSS3 layout built with [Foundation 6](http://foundation.zurb.com/sites.html) that looks great on all devices and screen sizes.\n* **Embed into your existing website**: An embedded option so that you can generate partial docs without a HTML `\u003cbody\u003e` tag for convenient integration into your existing website.\n* **Live preview developer mode**: Development mode that starts a local HTTP server with a file watcher and live reload, so you can preview live changes in your browser as you update your specification.\n\n## Usage\n\n### Install DociQL from `npm`:\n\n```bash\nnpm install -g dociql\n```\n\n\n### Define `config.yml` template to help generate beautiful docs:\n```yml\n# To fetch schema from\nintrospection: https://url-to-you-graphql-endpoint\n\nservers: # same format as for OpenAPI Specification\n  - url: https://dev-server.com\n    description: Dev\n  - url: https://prod-server.com\n    description: Prod\n    ...\n\ninfo: # same format as for OpenAPI Specification\n    title: Your API Title\n    description: Markdown enabled description of your api.    \n    ...\n\n # define your domains by providing a set of usecases\ndomains:\n  - name: Top Level Menu Section # Name of the domain\n    description: Description  # Description of the domain\n    usecases:         \n     - name: Fetch 'Some' field # Operation name\n       description: Markdown enabled description for operation # Opearation description\n       query: query.some # Query example - fetching single field\n       select: field1 field2 # select only specific sub fields. By default - all are selected\n       expand: field3(sub1, sub2, sub3),field4 # go deep by expanding specific fields.\n     - name: Invoke Mutation # Mutation \n       description: Markdown enabled description for operation\n       query: mutation.mutateSome # Mutation example - invoke mutation\n```\n### Pass your `config.yml` document to generate your documentation:\n\n```bash\ndociql -d config.yml\n```\n\nYour generated documentation will be located in the `public` directory by default. You can either copy the generated HTML to your web server, or view your docs by pointing your browser to [http://localhost:4400/](http://localhost:4400/).\n\n### Docker\n\n\u003e Coming soon!\n\n## Configuration Options\n\nThe basic CLI options are detailed below:\n\n```bash\n$ dociql -h\n\n  Usage: dociql [options] \u003cdociql.yaml\u003e\n\n  Options:\n\n    -h, --help                   output usage information\n    -H, --header                 specify a custom auth token for the header (default: none)\n    -V, --version                output the version number\n    -C, --disable-css            omit CSS generation (default: false)\n    -J, --disable-js             omit JavaScript generation (default: false)\n    -e, --embeddable             omit the HTML \u003cbody/\u003e and generate the documentation content only (default: false)\n    -d, --development-mode       start HTTP server with the file watcher (default: false)\n    -D, --development-mode-live  start HTTP server with the file watcher and live reload (default: false)\n    -s, --start-server           start the HTTP server without any development features\n    -p, --port \u003cport\u003e            the port number for the HTTP server to listen on (default: 4400)\n    -P, --port-live \u003cport\u003e       the port number for the live reload to listen on (default: 4401)\n    -t, --target-dir \u003cdir\u003e       the target build directory (default: public)\n    -f, --target-file \u003cfile\u003e     the target build HTML file (default: index.html)\n    -a, --app-dir \u003cdir\u003e          the application source directory (default: app)\n    -l, --logo-file \u003cfile\u003e       specify a custom logo file (default: null)\n    -1, --one-file               embed all resources (CSS and JS) into the same file (default: false)\n    -u, --introspection-url \u003curl\u003e              specify a custom url to use for introspection (default: none)\n    -c, --config-file \u003cfile\u003e     specify a custom configuration file (default: app/lib/config.js)\n```\n\nMost options are self explanatory, but the following options warrant some further explanation:\n\n* **--development-mode** `-d`: This option starts a development server with a file watcher, and will automatically regenerate your docs when any of your spec or app files change.\n\n* **--development-mode-live** `-D`: This option starts a development server with a file watcher and live reload, and will automatically regenerate your docs when any of your spec or app files change.\n\n* **--start-server** `-s`: This option starts a production server without any development options enabled that serves the contents of your `--target-dir`.\n\n* **--embeddable** `-e`: This option lets you build a minimal version of the documentation without the HTML `\u003cbody\u003e` tags, so you can embed DociQL into your own website template. More info on [Custom Builds](#custom-builds) here.\n\n* **--app-dir** `-a`: This option overrides the default directory which contains all the Handlebars templates, SCSS, and JavaScript source files. This option is useful for development because you can copy the contents of `app` to a remote location or a separate repo for custom builds.\n\n* **--target-dir** `-t`: This option specifies where the generated documentation HTML files will be output.\n\n## Custom Builds\n\nThe best option for building your own custom functionality into DociQL is to [fork DociQL on GitHub](https://help.github.com/articles/fork-a-repo/) and make your own modifications in the source. This way, you can keep up-to-date by merging changes from the `master` branch and you can also contribute your updates back to `master` by creating a [Pull Request](https://help.github.com/articles/creating-a-pull-request/), especially if you think they'll be an improvement for DociQL.\n\nTo fork DociQL go to `https://github.com/wayfair/dociql` and press the 'Fork' button. Now you can `git clone git@github.com:\u003cyourname\u003e/dociql.git` to make your own changes.\n\nAlternatively, you can just copy the contents of `app` from the main repo which contains all of the source files such as templates, stylesheets, and JavaScripts. Now, just pass the path from your custom `app` path to the CLI like so: `dociql -a dociql.json`.\n\n## Optimizing Your Workflow\n\nUsing an API spec to generate your documentation has a number of great advantages, such as:\n\n* **Maintain a single source**: Save time by removing the need to maintain a separate API spec and API documentation.\n* **No more out-of-date documentation**: Your documentation will always be up-to-date with your API spec.\n* **Be a better developer**: Your entire API system will be more stable and robust when built around your spec as a single source of truth.\n\n## Development\n\n### Testing\n\n\u003e Coming soon!\n\nTesting is powered by [Mocha](https://mochajs.org/)/[Chai](http://chaijs.com/) and automated testing is run via [CircleCI](https://circleci.com/).\n\nAt this stage, unit tests have not been written for all parts of the codebase.  However, new code should be tested, and unit tests for the existing code will be added in the future.\n\nRun `npm test` on the repository to start the automated tests. Some parts of testing can be configured using environment variables.\n\n- `OFFLINE=true`\n  Some tests use HTTP connections to test, giving DociQL remote API specifications. Use `OFFLINE=true` to skip tests that require an internet connection.\n\nInclude environment variables before calling `npm test`.  For example, `OFFLINE` mode can be enabled via `OFFLINE=true npm test`.\n\n\n\u003c!-- ## Contributors\n\nThanks to all the great developers who make DociQL great!\n\nTODO\n--\u003e\n\n\n## License\n\nDociQL is licensed under the Apache License 2.0 – see the [LICENSE.md](https://github.com/wayfair/dociql/blob/master/LICENSE) for specific details.\n\n## More Information\n\nMore info is available on the [DociQL homepage](https://github.com/wayfair/dociql).\n\nPlease use the [GitHub issue tracker](https://github.com/sourcey/spectacle/issues) if you have any ideas or bugs to report.\n\nAll contributions are welcome.\n\nGood luck and enjoy DociQL!\n\n[npm]: https://img.shields.io/npm/v/dociql.svg\n[npm-downloads]: https://img.shields.io/npm/dw/dociql\n[npm-url]: https://www.npmjs.com/package/dociql\n\n[builds]: https://app.travis-ci.com/wayfair/dociql.svg?branch=master\n[builds-url]: https://app.travis-ci.com/wayfair/dociql\n\n[cover]: https://codecov.io/gh/wayfair/dociql/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/wayfair/dociql\n\n[sonar]: https://sonarcloud.io/api/project_badges/measure?project=wayfair_dociql\u0026metric=alert_status\n[sonar-url]: https://sonarcloud.io/dashboard?id=wayfair_dociql\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayfair%2Fdociql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwayfair%2Fdociql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayfair%2Fdociql/lists"}