Skip to content

Commit

Permalink
implement docsify (mercurius-js#323)
Browse files Browse the repository at this point in the history
  • Loading branch information
PabloSzx authored Oct 18, 2020
1 parent 52f39d0 commit e061538
Show file tree
Hide file tree
Showing 11 changed files with 145 additions and 57 deletions.
48 changes: 23 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,23 +23,21 @@ npm i fastify mercurius

The previous name of this module is [fastify-gql](http://npm.im/fastify-gql) (< 6.0.0).

## Table of Contents

- [mercurius](#mercurius)
- [Install](#install)
- [Table of Contents](#table-of-contents)
- [Example](#example)
- [makeExecutableSchema support](#makeexecutableschema-support)
- [Context](#context)
- [API](#api)
- [Federation](#federation)
- [Subscriptions](#subscriptions)
- [Batched Queries](#batched-queries)
- [Persisted Queries](#persisted-queries)
- [Plugins](#plugins)
- [Integrations](#integrations)
- [Acknowledgements](#acknowledgements)
- [License](#license)
---
- [Install](#install)
- [Example](#example)
- [makeExecutableSchema support](#makeexecutableschema-support)
- [Context](#context)
- [API](#api)
- [Federation](#federation)
- [Subscriptions](#subscriptions)
- [Batched Queries](#batched-queries)
- [Persisted Queries](#persisted-queries)
- [Plugins](#plugins)
- [Integrations](#integrations)
- [Acknowledgements](#acknowledgements)
- [License](#license)
---

## Example

Expand Down Expand Up @@ -115,35 +113,35 @@ app.listen(3000)

## Context

[More info](./docs/context.md)
[More info](docs/context.md)

## API

[More info](./docs/api/options.md)
[More info](docs/api/options.md)

## Federation

[More info](./docs/federation.md)
[More info](docs/federation.md)

## Subscriptions

[More info](./docs/subscriptions.md)
[More info](docs/subscriptions.md)

## Batched Queries

[More info](./docs/batched-queries.md)
[More info](docs/batched-queries.md)

## Persisted Queries

[More info](./docs/persisted-queries.md)
[More info](docs/persisted-queries.md)

## Plugins

[More info](./docs/plugins.md)
[More info](docs/plugins.md)

## Integrations

[More info](./docs/integrations/index.md)
[More info](docs/integrations/)

## Acknowledgements

Expand Down
36 changes: 16 additions & 20 deletions docs/api/options.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,23 @@
# mercurius

- [mercurius](#mercurius)
- [API](#api)
- [plugin options](#plugin-options)
- [queryDepth example](#querydepth-example)
- [HTTP endpoints](#http-endpoints)
- [GET /graphql](#get-graphql)
- [POST /graphql](#post-graphql)
- [POST /graphql with Content-type: application/graphql](#post-graphql-with-content-type-applicationgraphql)
- [GET /graphiql](#get-graphiql)
- [GET /playground](#get-playground)
- [decorators](#decorators)
- [app.graphql(source, context, variables, operationName)](#appgraphqlsource-context-variables-operationname)
- [app.graphql.extendSchema(schema) and app.graphql.defineResolvers(resolvers)](#appgraphqlextendschemaschema-and-appgraphqldefineresolversresolvers)
- [app.graphql.replaceSchema(schema)](#appgraphqlreplaceschemaschema)
- [app.graphql.schema](#appgraphqlschema)
- [app.graphql.transformSchema(transforms)](#appgraphqltransformschematransforms)
- [app.graphql.defineLoaders(loaders)](#appgraphqldefineloadersloaders)
- [reply.graphql(source, context, variables, operationName)](#replygraphqlsource-context-variables-operationname)
- [Plugin options](#plugin-options)
- [HTTP endpoints](#http-endpoints)
- [GET /graphql](#get-graphql)
- [POST /graphql](#post-graphql)
- [POST /graphql with Content-type: application/graphql](#post-graphql-with-content-type-applicationgraphql)
- [GET /graphiql](#get-graphiql)
- [GET /playground](#get-playground)
- [Decorators](#decorators)
- [app.graphql(source, context, variables, operationName)](#appgraphqlsource-context-variables-operationname)
- [app.graphql.extendSchema(schema) and app.graphql.defineResolvers(resolvers)](#appgraphqlextendschemaschema-and-appgraphqldefineresolversresolvers)
- [app.graphql.replaceSchema(schema)](#appgraphqlreplaceschemaschema)
- [app.graphql.schema](#appgraphqlschema)
- [app.graphql.defineLoaders(loaders)](#appgraphqldefineloadersloaders)
- [reply.graphql(source, context, variables, operationName)](#replygraphqlsource-context-variables-operationname)

## API

### plugin options
### Plugin options

**mercurius** supports the following options:

Expand Down Expand Up @@ -172,7 +168,7 @@ the options.
Serves [GraphQL IDE](https://www.npmjs.com/package/graphql-playground-react) if enabled by
the options.

### decorators
### Decorators

**mercurius** adds the following decorators.

Expand Down
10 changes: 10 additions & 0 deletions docs/federation.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# mercurius


- [Federation metadata support](#federation-metadata-support)
- [Federation with \_\_resolveReference caching](#federation-with-__resolvereference-caching)
- [Use GraphQL server as a Gateway for federated schemas](#use-graphql-server-as-a-gateway-for-federated-schemas)
- [Periodically refresh federated schemas in Gateway mode](#periodically-refresh-federated-schemas-in-gateway-mode)
- [Programmatically refresh federated schemas in Gateway mode](#programmatically-refresh-federated-schemas-in-gateway-mode)
- [Flag a service as mandatory in Gateway mode](#flag-a-service-as-mandatory-in-gateway-mode)
- [Using a custom errorHandler for handling downstream service errors in Gateway mode](#using-a-custom-errorhandler-for-handling-downstream-service-errors-in-gateway-mode)
- [Use errors extension to provide additional information to query errors](#use-errors-extension-to-provide-additional-information-to-query-errors)

## Federation

### Federation metadata support
Expand Down
5 changes: 5 additions & 0 deletions docs/integrations/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# mercurius

## Integrations

- [@nexus/schema](/docs/integrations/nexus-schema) - Declarative, code-first and strongly typed GraphQL schema construction for TypeScript & JavaScript
5 changes: 0 additions & 5 deletions docs/integrations/index.md

This file was deleted.

8 changes: 4 additions & 4 deletions docs/persisted-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Persisted Queries solve this problem by having the client send a generated ID, i

The `persistedQueryProvider` option lets you configure this for Fastify mercurius. There are a few default options available, included in `mercurius.persistedQueryDefaults`.

#### Prepared
### Prepared

Prepared queries give the best performance in all use cases, at the expense of tooling complexity. Queries must be hashed ahead of time, and a matching set of hashes must be available for both the client and the server. Additionally, version control of query hashes must be considered, e.g. queries used by old clients may need to be kept such that hashes can be calculated at build time. This can be very useful for non-public APIs, but is impractical for public APIs.

Expand Down Expand Up @@ -49,7 +49,7 @@ app.register(mercurius, {
})
```

#### Prepared Only
### Prepared Only

This offers similar performance and considerations to the `prepared` queries, but only allows persisted queries. This provides additional secuirity benefits, but means that the server **must** know all queries ahead of time or will reject the request.

Expand All @@ -69,7 +69,7 @@ app.register(mercurius, {
})
```

#### Automatic
### Automatic

This default is compatible with `apollo-client`, and requires no additional tooling to set up at the cost of some performance. In order for this mode to be effective, you must have long lived server instances (i.e _not_ cloud functions). This mode is also appropriate for public APIs where queries are not known ahead of time.

Expand Down Expand Up @@ -103,7 +103,7 @@ app.register(mercurius, {
})
```

#### Custom Persisted Queries
### Custom Persisted Queries

It is also possible to extend or modify these persisted query implementations for custom cases, such as automatic Persisted Queries, but with a shared cache between servers.

Expand Down
2 changes: 1 addition & 1 deletion docs/protocol-extension.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# GraphQL over WebSocket Protocol extension

The GraphQL over WebSocket Protocol used by `mercurius` follows apollo's protocol defined (here)[https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md]. In order to achieve gateway-to-service communication and handle `connection_init` per client, an extension is used on the protocol for server-to-server communication.
The GraphQL over WebSocket Protocol used by `mercurius` follows apollo's protocol defined [here](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md). In order to achieve gateway-to-service communication and handle `connection_init` per client, an extension is used on the protocol for server-to-server communication.

## Message structure extension

Expand Down
4 changes: 2 additions & 2 deletions docs/subscriptions.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# mercurius

## Subscriptions

- [Subscriptions](#subscriptions)
- [Subscription support (simple)](#subscription-support-simple)
- [Build a custom GraphQL context object for subscriptions](#build-a-custom-graphql-context-object-for-subscriptions)
- [Subscription support (with redis)](#subscription-support-with-redis)

## Subscriptions

### Subscription support (simple)

```js
Expand Down
21 changes: 21 additions & 0 deletions docsify/sidebar.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@

* [**Home**](/)
* [Install](/#install)
* [Example](/#example)
* [Executable schema](/#makeexecutableschema-support)
* [Acknowledgements](/#acknowledgements)
* [License](/#license)
* [API](/docs/api/options)
* [Plugins options](/docs/api/options#plugin-options)
* [HTTP Endpoints](/docs/api/options#http-endpoints)
* [Decorators](/docs/api/options#decorators)
* [Context](/docs/context)
* [Federation](/docs/federation)
* [Subscriptions](/docs/subscriptions)
* [Batched Queries](/docs/batched-queries)
* [Persisted Queries](/docs/persisted-queries)
* [Integrations](/docs/integrations/)
* [@nexus/schema](/docs/integrations/nexus-schema)
* [Related plugins](/docs/plugins)
* [mercurius-upload](/docs/plugins)
* [Protocol extensions](/docs/protocol-extension)
61 changes: 61 additions & 0 deletions index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Mercurius</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description" />
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
/>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"
/>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"
media="(prefers-color-scheme: dark)"
/>

<style>
:root {
--base-font-size: 16px;
--theme-color: rgb(238, 156, 62);
--link-color: rgb(238, 156, 62);
--link-color--hover: rgb(238, 156, 62);
--sidebar-name-margin: 0;
--sidebar-name-padding: 0;
--code-font-size: 0.9em;
}
.sidebar > h1 {
margin-bottom: -0.75em;
margin-top: 0.75em;
}
.sidebar > h1 img {
height: 4em;
}
.markdown-section a code {
color: var(--link-color) !important;
}
.markdown-section code:not([class*='lang-']):not([class*='language-']) {
white-space: unset;
}
</style>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
loadSidebar: 'docsify/sidebar.md',
name: 'Mercurius',
repo: 'https://github.com/mercurius-js/mercurius',
auto2top: true
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
</body>
</html>
2 changes: 2 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"main": "index.js",
"types": "index.d.ts",
"scripts": {
"docs": "docsify serve",
"unit": "tap --100 test/*.js test/gateway/*.js",
"cov": "tap --coverage-report=html -J test/*.js test/gateway/*.js",
"lint": "npm run lint:standard && npm run lint:typescript",
Expand All @@ -30,6 +31,7 @@
"@typescript-eslint/eslint-plugin": "^3.6.1",
"@typescript-eslint/parser": "^3.6.1",
"autocannon": "^6.0.0",
"docsify-cli": "^4.4.1",
"fastify": "^3.0.2",
"graphql-tools": "^6.0.14",
"pre-commit": "^1.2.2",
Expand Down

0 comments on commit e061538

Please sign in to comment.