add: Schema and Tags Options (#65)

Author: climba03003

README.md

@@ -85,6 +85,34 @@ fastify.register(oauthPlugin, {
 })
 ```
 
+### Schema configuration
+
+You can specify your own schema for the `startRedirectPath` end-point. It allows you to create a well-documented document when using `fastify-swagger` together.
+Note: `schema` option will override the `tags` option without merge them.
+
+```js
+fastify.register(oauthPlugin, {
+  name: 'facebookOAuth2',
+  credentials: {
+    client: {
+      id: '<CLIENT_ID>',
+      secret: '<CLIENT_SECRET>'
+    },
+    auth: oauthPlugin.FACEBOOK_CONFIGURATION
+  },
+  // register a fastify url to start the redirect flow
+  startRedirectPath: '/login/facebook',
+  // facebook redirect here after the user login
+  callbackUri: 'http://localhost:3000/login/facebook/callback',
+  // add tags for the schema
+  tags: ['facebook', 'oauth2'],
+  // add schema
+  schema: {
+    tags: ['facebook', 'oauth2'] // this will take the precedence
+  }
+})
+```
+
 ## Set custom state
 
 The `generateStateFunction` accepts a function to generate the `state` parameter for the OAUTH flow. This function receives the Fastify's `request` object as parameter.

index.d.ts

@@ -66,6 +66,8 @@ declare namespace fastifyOauth2 {
     generateStateFunction?: Function;
     checkStateFunction?: Function;
     startRedirectPath: string;
+    tags?: string[];
+    schema?: object;
   }
 }
 

index.js

@@ -45,6 +45,12 @@ const oauthPlugin = fp(function (fastify, options, next) {
   if (!options.generateStateFunction ^ !options.checkStateFunction) {
     return next(new Error('options.checkStateFunction and options.generateStateFunction have to be given'))
   }
+  if (options.tags && !Array.isArray(options.tags)) {
+    return next(new Error('options.tags should be a array'))
+  }
+  if (options.schema && typeof options.schema !== 'object') {
+    return next(new Error('options.schema should be a object'))
+  }
 
   const name = options.name
   const credentials = options.credentials
@@ -54,6 +60,8 @@ const oauthPlugin = fp(function (fastify, options, next) {
   const generateStateFunction = options.generateStateFunction || defaultGenerateStateFunction
   const checkStateFunction = options.checkStateFunction || defaultCheckStateFunction
   const startRedirectPath = options.startRedirectPath
+  const tags = options.tags || []
+  const schema = options.schema || { tags: tags }
 
   function generateAuthorizationUri (requestObject) {
     const state = generateStateFunction(requestObject)
@@ -116,7 +124,7 @@ const oauthPlugin = fp(function (fastify, options, next) {
   const oauth2 = oauth2Module.create(credentials)
 
   if (startRedirectPath) {
-    fastify.get(startRedirectPath, startRedirectHandler)
+    fastify.get(startRedirectPath, { schema }, startRedirectHandler)
   }
 
   try {

index.test-d.ts

@@ -8,6 +8,7 @@ import { Server, IncomingMessage, ServerResponse } from 'http';
  */
 const auth = fastifyOauth2.GOOGLE_CONFIGURATION;
 const scope = ['r_emailaddress', 'r_basicprofile'];
+const tags = ['oauth2', 'oauth'];
 const credentials = {
   client: {
     id: 'test_id',
@@ -42,6 +43,7 @@ declare module 'fastify' {
  */
 expectType<fastifyOauth2.ProviderConfiguration>(auth);
 expectType<string[]>(scope);
+expectType<string[]>(tags);
 expectType<fastifyOauth2.Credentials>(credentials);
 
 expectError(fastifyOauth2()); // error because missing required arguments

test.js

@@ -468,6 +468,81 @@ t.test('options.generateStateFunction ^ options.checkStateFunction', t => {
     })
 })
 
+t.test('options.tags should be a array', t => {
+  t.plan(1)
+
+  const fastify = createFastify({ logger: { level: 'silent' } })
+
+  fastify.register(oauthPlugin, {
+    name: 'the-name',
+    credentials: {
+      client: {
+        id: 'my-client-id',
+        secret: 'my-secret'
+      },
+      auth: oauthPlugin.GITHUB_CONFIGURATION
+    },
+    callbackUri: '/callback',
+    tags: 'invalid tags'
+  })
+    .ready(err => {
+      t.strictSame(err.message, 'options.tags should be a array')
+    })
+})
+
+t.test('options.schema should be a object', t => {
+  t.plan(1)
+
+  const fastify = createFastify({ logger: { level: 'silent' } })
+
+  fastify.register(oauthPlugin, {
+    name: 'the-name',
+    credentials: {
+      client: {
+        id: 'my-client-id',
+        secret: 'my-secret'
+      },
+      auth: oauthPlugin.GITHUB_CONFIGURATION
+    },
+    callbackUri: '/callback',
+    schema: 1
+  })
+    .ready(err => {
+      t.strictSame(err.message, 'options.schema should be a object')
+    })
+})
+
+t.test('options.schema', t => {
+  const fastify = createFastify({ logger: { level: 'silent' } })
+
+  fastify.addHook('onRoute', function (routeOptions) {
+    t.strictSame(routeOptions.schema, { tags: ['oauth2', 'oauth'] })
+    t.end()
+  })
+
+  fastify.register(oauthPlugin, {
+    name: 'the-name',
+    credentials: {
+      client: {
+        id: 'my-client-id',
+        secret: 'my-secret'
+      },
+      auth: oauthPlugin.GITHUB_CONFIGURATION
+    },
+    startRedirectPath: '/login/github',
+    callbackUri: '/callback',
+    callbackUriParams: {
+      access_type: 'offline'
+    },
+    scope: ['notifications'],
+    schema: {
+      tags: ['oauth2', 'oauth']
+    }
+  })
+
+  fastify.ready()
+})
+
 t.test('already decorated', t => {
   t.plan(1)