Document endpoint customization (#2730)

* document express customization of express endpoint * document express customization of fastify endpoint * better endpoint binding in documentation * update examples to explicitly use graphqlEndpoint * fix start message * fix fastify example tests * fix fastify-modules example tests * run prettier
dotansimha · May 5, 2023 · af1948f · af1948f
1 parent 2234a6a
commit af1948f
Show file tree

Hide file tree

Showing 31 changed files with 96 additions and 50 deletions.
diff --git a/examples/apollo-federation/gateway/index.js b/examples/apollo-federation/gateway/index.js
@@ -15,7 +15,9 @@ async function main() {
   // Start the server and explore http://localhost:4000/graphql
   const server = createServer(yoga)
   server.listen(4000, () => {
-    console.info('Server is running on http://localhost:4000/graphql')
+    console.info(
+      `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+    )
   })
 }
 

diff --git a/examples/cookies/src/index.ts b/examples/cookies/src/index.ts
@@ -3,5 +3,7 @@ import { app } from './app'
 
 const server = createServer(app)
 server.listen(4000, () => {
-  console.info(`Server is running on http://localhost:4000/graphql`)
+  console.info(
+    `Server is running on http://localhost:4000${app.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/defer-stream/src/index.ts b/examples/defer-stream/src/index.ts
@@ -3,5 +3,7 @@ import { createServer } from 'http'
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/deno/index.ts b/examples/deno/index.ts
@@ -3,6 +3,8 @@ import { yoga } from './yoga.ts'
 
 serve(yoga, {
   onListen({ hostname, port }) {
-    console.log(`Listening on http://${hostname}:${port}/graphql`)
+    console.log(
+      `Listening on http://${hostname}:${port}${yoga.graphqlEndpoint}`,
+    )
   },
 })
diff --git a/examples/error-handling/src/index.ts b/examples/error-handling/src/index.ts
@@ -4,5 +4,7 @@ import { yoga } from './yoga'
 // Start the server and explore http://localhost:4000/graphql
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/express/src/app.ts b/examples/express/src/app.ts
@@ -38,7 +38,7 @@ export function buildApp(app: ReturnType<typeof express>) {
     logging: false,
   })
 
-  app.use('/graphql', graphQLServer)
+  app.use(graphQLServer.graphqlEndpoint, graphQLServer)
 
-  return app
+  return graphQLServer.graphqlEndpoint
 }
diff --git a/examples/express/src/index.ts b/examples/express/src/index.ts
@@ -3,8 +3,8 @@ import { buildApp } from './app'
 
 const app = express()
 
-buildApp(app)
+const endpoint = buildApp(app)
 
 app.listen(4000, () => {
-  console.log('GraphQL API located at http://localhost:4000/graphql')
+  console.log(`GraphQL API located at http://localhost:4000${endpoint}`)
 })
diff --git a/examples/fastify-modules/__integration-test__/fastify-modules.spec.ts b/examples/fastify-modules/__integration-test__/fastify-modules.spec.ts
@@ -3,7 +3,7 @@ import request from 'supertest'
 import { buildApp } from '../src/app.js'
 
 describe('fastify-modules example integration', () => {
-  const app = buildApp()
+  const [app] = buildApp()
 
   beforeAll(async () => {
     await app.ready()

diff --git a/examples/fastify-modules/src/app.ts b/examples/fastify-modules/src/app.ts
@@ -15,7 +15,9 @@ export function createGraphQLApp() {
   })
 }
 
-export function createGraphQLHandler(): RouteHandlerMethod {
+export function createGraphQLHandler(): RouteHandlerMethod & {
+  endpoint: string
+} {
   const graphQLServer = createYoga<{
     req: FastifyRequest
     reply: FastifyReply
@@ -24,7 +26,7 @@ export function createGraphQLHandler(): RouteHandlerMethod {
     plugins: [useGraphQLModules(createGraphQLApp())],
   })
 
-  return async (req, reply) => {
+  const handler = async (req, reply) => {
     const response = await graphQLServer.handleNodeRequest(req, {
       req,
       reply,
@@ -39,16 +41,20 @@ export function createGraphQLHandler(): RouteHandlerMethod {
 
     return reply
   }
+
+  handler.endpoint = graphQLServer.graphqlEndpoint
+  return handler
 }
 
 export function buildApp() {
   const app = fastify({ logger: false })
+  const handler = createGraphQLHandler()
 
   app.route({
-    url: '/graphql',
+    url: handler.endpoint,
     method: ['GET', 'POST', 'OPTIONS'],
-    handler: createGraphQLHandler(),
+    handler,
   })
 
-  return app
+  return [app, handler.endpoint] as const
 }
diff --git a/examples/fastify-modules/src/index.ts b/examples/fastify-modules/src/index.ts
@@ -1,13 +1,13 @@
 import { buildApp } from './app'
 
-const app = buildApp()
+const [app, endpoint] = buildApp()
 
 app
   .listen({
     port: 4000,
   })
   .then((serverUrl) => {
-    app.log.info(`GraphQL API located at ${serverUrl}/graphql`)
+    app.log.info(`GraphQL API located at ${serverUrl}${endpoint}`)
   })
   .catch((err) => {
     app.log.error(err)

diff --git a/examples/fastify/__integration-tests__/fastify.spec.ts b/examples/fastify/__integration-tests__/fastify.spec.ts
@@ -2,7 +2,7 @@ import request from 'supertest'
 import { buildApp } from '../src/app.js'
 
 describe('fastify example integration', () => {
-  const app = buildApp(false)
+  const [app] = buildApp(false)
 
   beforeAll(async () => {
     await app.ready()

diff --git a/examples/fastify/src/app.ts b/examples/fastify/src/app.ts
@@ -68,7 +68,7 @@ export function buildApp(logging = true) {
   )
 
   app.route({
-    url: '/graphql',
+    url: graphQLServer.graphqlEndpoint,
     method: ['GET', 'POST', 'OPTIONS'],
     handler: async (req, reply) => {
       const response = await graphQLServer.handleNodeRequest(req, {
@@ -87,5 +87,5 @@ export function buildApp(logging = true) {
     },
   })
 
-  return app
+  return [app, graphQLServer.graphqlEndpoint] as const
 }
diff --git a/examples/fastify/src/index.ts b/examples/fastify/src/index.ts
@@ -1,13 +1,13 @@
 import { buildApp } from './app'
 
-const app = buildApp(true)
+const [app, endpoint] = buildApp(true)
 
 app
   .listen({
     port: 4000,
   })
   .then((serverUrl) => {
-    app.log.info(`GraphQL API located at ${serverUrl}/graphql`)
+    app.log.info(`GraphQL API located at ${serverUrl}${endpoint}`)
   })
   .catch((err) => {
     app.log.error(err)

diff --git a/examples/file-upload-nexus/index.ts b/examples/file-upload-nexus/index.ts
@@ -5,5 +5,7 @@ const server = createServer(yoga)
 
 // Start the server and explore http://localhost:4000/graphql
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/file-upload/index.ts b/examples/file-upload/index.ts
@@ -3,5 +3,7 @@ import { yoga } from './yoga'
 
 const server = http.createServer(yoga)
 server.listen(4000, () => {
-  console.log('Server listening on http://localhost:4000/graphql')
+  console.log(
+    `Server listening on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/generic-auth/src/main.ts b/examples/generic-auth/src/main.ts
@@ -3,5 +3,7 @@ import { yoga } from './app'
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/graphql-armor/src/main.ts b/examples/graphql-armor/src/main.ts
@@ -3,5 +3,7 @@ import { yoga } from './yoga'
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/hackernews/src/main.ts b/examples/hackernews/src/main.ts
@@ -7,7 +7,9 @@ function main() {
   const yoga = createYoga({ schema, context: createContext })
   const server = createServer(yoga)
   server.listen(4000, () => {
-    console.info('Server is running on http://localhost:4000/graphql')
+    console.info(
+      `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+    )
   })
 }
 

diff --git a/examples/hello-world/index.js b/examples/hello-world/index.js
@@ -30,5 +30,7 @@ const yoga = createYoga({
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.log('Server is running on http://localhost:4000/graphql')
+  console.log(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/issue-template/src/main.ts b/examples/issue-template/src/main.ts
@@ -27,5 +27,7 @@ const yoga = createYoga({
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/live-query/src/main.ts b/examples/live-query/src/main.ts
@@ -44,5 +44,7 @@ const yoga = createYoga<{ greetings: Array<string> }>({
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/node-esm/index.mjs b/examples/node-esm/index.mjs
@@ -3,5 +3,5 @@ import { createServer } from 'http'
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.info('Server started on http://localhost:4000/graphql')
+  console.info(`Server started on http://localhost:4000${yoga.graphqlEndpoint}`)
 })
diff --git a/examples/node-ts/src/index.ts b/examples/node-ts/src/index.ts
@@ -3,5 +3,5 @@ import { yoga } from './yoga'
 
 const server = createServer(yoga)
 server.listen(4000, () => {
-  console.log(`Listening on http://localhost:4000/graphql`)
+  console.log(`Listening on http://localhost:4000${yoga.graphqlEndpoint}`)
 })
diff --git a/examples/pothos/src/index.ts b/examples/pothos/src/index.ts
@@ -4,5 +4,7 @@ import { yoga } from './yoga'
 const server = createServer(yoga)
 
 server.listen(4000, () => {
-  console.info('Server is running on http://localhost:4000/graphql')
+  console.info(
+    `Server is running on http://localhost:4000${yoga.graphqlEndpoint}`,
+  )
 })
diff --git a/examples/sofa/src/index.ts b/examples/sofa/src/index.ts
@@ -1,4 +1,4 @@
-import { yoga } from './yoga'
+import { yoga, swaggerEndpoint, restEndpoint } from './yoga'
 import { createServer } from 'http'
 import { titleBold, infoColor } from 'graphql-yoga'
 
@@ -12,18 +12,20 @@ server.listen(4000, async () => {
   }
 
   console.log(`
-    ${titleBold('Swagger UI: ')}    ${printUrl('/swagger')}
+    ${titleBold('Swagger UI: ')}    ${printUrl(swaggerEndpoint)}
 
-    ${titleBold('GraphQL:')}        ${printUrl('/graphql')}
+    ${titleBold('GraphQL:')}        ${printUrl(yoga.graphqlEndpoint)}
 
     ${titleBold('Queries:')}
-      me:           ${printUrl('/rest/me')}
-      users:        ${printUrl('/rest/users')}
-      user:         ${printUrl('/rest/user/1')}
-      books:        ${printUrl('/rest/books')}
-      book:         ${printUrl('/rest/book/1')}
+      me:           ${printUrl(`${restEndpoint}/me`)}
+      users:        ${printUrl(`${restEndpoint}/users`)}
+      user:         ${printUrl(`${restEndpoint}/user/1`)}
+      books:        ${printUrl(`${restEndpoint}/books`)}
+      book:         ${printUrl(`${restEndpoint}/book/1`)}
 
     ${titleBold('Mutations:')}
-      addBook:      ${printUrl('/rest/add-book')} ${infoColor('POST: {title}')}
+      addBook:      ${printUrl(`${restEndpoint}/add-book`)} ${infoColor(
+    'POST: {title}',
+  )}
   `)
 })
diff --git a/examples/sofa/src/yoga.ts b/examples/sofa/src/yoga.ts
@@ -218,12 +218,15 @@ const schema = createSchema({
   },
 })
 
+export const swaggerEndpoint = '/swagger'
+export const restEndpoint = '/rest'
+
 export const yoga = createYoga({
   schema,
   plugins: [
     useSofaWithSwaggerUI({
-      basePath: '/rest',
-      swaggerUIEndpoint: '/swagger',
+      basePath: restEndpoint,
+      swaggerUIEndpoint: swaggerEndpoint,
       servers: [
         {
           url: '/', // Specify Server's URL.

diff --git a/examples/uwebsockets/src/app.ts b/examples/uwebsockets/src/app.ts
@@ -133,4 +133,6 @@ const wsHandler = makeBehavior({
   },
 })
 
-export const app = App().any('/*', yogaHandler).ws('/graphql', wsHandler)
+export const app = App()
+  .any('/*', yogaHandler)
+  .ws(yoga.graphqlEndpoint, wsHandler)
diff --git a/website/src/pages/docs/integrations/integration-with-deno.mdx b/website/src/pages/docs/integrations/integration-with-deno.mdx
@@ -43,7 +43,9 @@ const yoga = createYoga({
 
 serve(yoga, {
   onListen({ hostname, port }) {
-    console.log(`Listening on http://${hostname}:${port}/graphql`)
+    console.log(
+      `Listening on http://${hostname}:${port}/${yoga.graphqlEndpoint}}`
+    )
   }
 })
 ```

diff --git a/website/src/pages/docs/integrations/integration-with-express.mdx b/website/src/pages/docs/integrations/integration-with-express.mdx
@@ -28,8 +28,8 @@ const app = express()
 
 const yoga = createYoga()
 
-// Bind GraphQL Yoga to `/graphql` endpoint
-app.use('/graphql', yoga)
+// Bind GraphQL Yoga to the graphql endpoint to avoid rendering the playground on any path
+app.use(yoga.graphqlEndpoint, yoga)
 
 app.listen(4000, () => {
   console.log('Running a GraphQL API server at http://localhost:4000/graphql')

diff --git a/website/src/pages/docs/integrations/integration-with-fastify.mdx b/website/src/pages/docs/integrations/integration-with-fastify.mdx
@@ -44,7 +44,8 @@ const yoga = createYoga<{
  * Learn more about `reply` https://www.fastify.io/docs/latest/Reply/
  **/
 app.route({
-  url: '/graphql',
+  // Bind to the Yoga's endpoint to avoid rendering on any path
+  url: yoga.graphqlEndpoint,
   method: ['GET', 'POST', 'OPTIONS'],
   handler: async (req, reply) => {
     // Second parameter adds Fastify's `req` and `reply` to the GraphQL Context

diff --git a/website/src/pages/docs/integrations/integration-with-koa.mdx b/website/src/pages/docs/integrations/integration-with-koa.mdx
@@ -41,7 +41,9 @@ app.use(async (ctx) => {
 })
 
 app.listen(4000, () => {
-  console.log('Running a GraphQL API server at http://localhost:4000')
+  console.log(
+    `Running a GraphQL API server at http://localhost:4000/${yoga.graphqlEndpoint}`
+  )
 })
 ```