feat: added option to hide untagged routes (#406)

* added option to hide untagged routes * shouldRouteHide function accept options parameter * Use the right naming in swagger test case
fastify · Apr 22, 2021 · 7c3d58c · 7c3d58c
1 parent 5caace8
commit 7c3d58c
Show file tree

Hide file tree

Showing 11 changed files with 176 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -177,6 +177,7 @@ fastify.ready(err => {
  | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------- |
  | exposeRoute        | false     | Exposes documentation route.                                                                                              |
  | hiddenTag          | X-HIDDEN  | Tag to control hiding of routes.                                                                                          |
+ | hideUntagged       | false     | If true remove routes without tags in schema from resulting swagger file                                                  |
  | stripBasePath      | true      | Strips base path from routes in docs.                                                                                     |
  | swagger            | {}        | Swagger configuration.                                                                                                    |
  | openapi            | {}        | OpenAPI configuration.                                                                                                    |

diff --git a/examples/dynamic-openapi.js b/examples/dynamic-openapi.js
@@ -22,6 +22,7 @@ fastify.register(require('../index'), {
       }
     }
   },
+  hideUntagged: true,
   exposeRoute: true
 })
 
@@ -64,6 +65,44 @@ fastify.put('/some-route/:id', {
   }
 }, (req, reply) => { reply.send({ hello: `Hello ${req.body.hello}` }) })
 
+fastify.post('/some-route/:id', {
+  schema: {
+    description: 'post some data',
+    summary: 'qwerty',
+    security: [{ apiKey: [] }],
+    params: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'user id'
+        }
+      }
+    },
+    body: {
+      type: 'object',
+      properties: {
+        hello: { type: 'string' },
+        obj: {
+          type: 'object',
+          properties: {
+            some: { type: 'string' }
+          }
+        }
+      }
+    },
+    response: {
+      201: {
+        description: 'Succesful response',
+        type: 'object',
+        properties: {
+          hello: { type: 'string' }
+        }
+      }
+    }
+  }
+}, (req, reply) => { reply.send({ hello: `Hello ${req.body.hello}` }) })
+
 fastify.listen(3000, err => {
   if (err) throw err
   console.log('listening')

diff --git a/examples/dynamic-swagger.js b/examples/dynamic-swagger.js
@@ -21,6 +21,7 @@ fastify.register(require('../index'), {
     consumes: ['application/json'],
     produces: ['application/json']
   },
+  hideUntagged: true,
   exposeRoute: true
 })
 
@@ -63,6 +64,44 @@ fastify.put('/some-route/:id', {
   }
 }, (req, reply) => { reply.send({ hello: `Hello ${req.body.hello}` }) })
 
+fastify.post('/some-route/:id', {
+  schema: {
+    description: 'post some data',
+    summary: 'qwerty',
+    security: [{ apiKey: [] }],
+    params: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'user id'
+        }
+      }
+    },
+    body: {
+      type: 'object',
+      properties: {
+        hello: { type: 'string' },
+        obj: {
+          type: 'object',
+          properties: {
+            some: { type: 'string' }
+          }
+        }
+      }
+    },
+    response: {
+      201: {
+        description: 'Succesful response',
+        type: 'object',
+        properties: {
+          hello: { type: 'string' }
+        }
+      }
+    }
+  }
+}, (req, reply) => { reply.send({ hello: `Hello ${req.body.hello}` }) })
+
 fastify.listen(3000, err => {
   if (err) throw err
   console.log('listening')

diff --git a/lib/mode/dynamic.js b/lib/mode/dynamic.js
@@ -8,6 +8,7 @@ module.exports = function (fastify, opts, done) {
   opts = Object.assign({}, {
     exposeRoute: false,
     hiddenTag: 'X-HIDDEN',
+    hideUntagged: false,
     stripBasePath: true,
     openapi: null,
     swagger: {},

diff --git a/lib/spec/openapi/index.js b/lib/spec/openapi/index.js
@@ -36,7 +36,12 @@ module.exports = function (opts, cache, routes, Ref, done) {
         ? defOpts.transform(route.schema)
         : route.schema
 
-      if (shouldRouteHide(schema, defOpts.hiddenTag)) continue
+      const shouldRouteHideOpts = {
+        hiddenTag: defOpts.hiddenTag,
+        hideUntagged: defOpts.hideUntagged
+      }
+
+      if (shouldRouteHide(schema, shouldRouteHideOpts)) continue
 
       const url = normalizeUrl(route.url, defOpts.servers, defOpts.stripBasePath)
 

diff --git a/lib/spec/openapi/utils.js b/lib/spec/openapi/utils.js
@@ -15,6 +15,7 @@ function prepareDefaultOptions (opts) {
   const stripBasePath = opts.stripBasePath
   const transform = opts.transform
   const hiddenTag = opts.hiddenTag
+  const hideUntagged = opts.hideUntagged
   const extensions = []
 
   for (const [key, value] of Object.entries(opts.openapi)) {
@@ -33,7 +34,8 @@ function prepareDefaultOptions (opts) {
     stripBasePath,
     transform,
     hiddenTag,
-    extensions
+    extensions,
+    hideUntagged
   }
 }
 

diff --git a/lib/spec/swagger/index.js b/lib/spec/swagger/index.js
@@ -36,7 +36,12 @@ module.exports = function (opts, cache, routes, Ref, done) {
         ? defOpts.transform(route.schema)
         : route.schema
 
-      if (shouldRouteHide(schema, defOpts.hiddenTag)) continue
+      const shouldRouteHideOpts = {
+        hiddenTag: defOpts.hiddenTag,
+        hideUntagged: defOpts.hideUntagged
+      }
+
+      if (shouldRouteHide(schema, shouldRouteHideOpts)) continue
 
       const url = normalizeUrl(route.url, defOpts.basePath, defOpts.stripBasePath)
 

diff --git a/lib/spec/swagger/utils.js b/lib/spec/swagger/utils.js
@@ -19,6 +19,7 @@ function prepareDefaultOptions (opts) {
   const stripBasePath = opts.stripBasePath
   const transform = opts.transform
   const hiddenTag = opts.hiddenTag
+  const hideUntagged = opts.hideUntagged
   const extensions = []
 
   for (const [key, value] of Object.entries(opts.swagger)) {
@@ -42,7 +43,8 @@ function prepareDefaultOptions (opts) {
     stripBasePath,
     transform,
     hiddenTag,
-    extensions
+    extensions,
+    hideUntagged
   }
 }
 

diff --git a/lib/util/common.js b/lib/util/common.js
@@ -41,13 +41,23 @@ function addHook (fastify) {
   }
 }
 
-function shouldRouteHide (schema, hiddenTag) {
+function shouldRouteHide (schema, opts) {
+  const { hiddenTag, hideUntagged } = opts
+
   if (schema && schema.hide) {
     return true
   }
-  if (schema && schema.tags && schema.tags.includes(hiddenTag)) {
+
+  const tags = (schema && schema.tags) || []
+
+  if (tags.length === 0 && hideUntagged) {
+    return true
+  }
+
+  if (tags.includes(hiddenTag)) {
     return schema.tags.includes(hiddenTag)
   }
+
   return false
 }
 

diff --git a/test/spec/openapi/option.js b/test/spec/openapi/option.js
@@ -213,6 +213,39 @@ test('hide support - tags Custom', t => {
   })
 })
 
+test('hide support - hidden untagged', t => {
+  t.plan(2)
+  const fastify = Fastify()
+
+  fastify.register(fastifySwagger, { ...openapiOption, hideUntagged: true })
+
+  const opts = {
+    schema: {
+      body: {
+        type: 'object',
+        properties: {
+          hello: { type: 'string' },
+          obj: {
+            type: 'object',
+            properties: {
+              some: { type: 'string' }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  fastify.get('/', opts, () => {})
+
+  fastify.ready(err => {
+    t.error(err)
+
+    const openapiObject = fastify.swagger()
+    t.notOk(openapiObject.paths['/'])
+  })
+})
+
 test('basePath support', t => {
   t.plan(3)
   const fastify = Fastify()

diff --git a/test/spec/swagger/option.js b/test/spec/swagger/option.js
@@ -386,6 +386,39 @@ test('hide support - tags Custom', t => {
   })
 })
 
+test('hide support - hidden untagged', t => {
+  t.plan(2)
+  const fastify = Fastify()
+
+  fastify.register(fastifySwagger, { ...swaggerOption, hideUntagged: true })
+
+  const opts = {
+    schema: {
+      body: {
+        type: 'object',
+        properties: {
+          hello: { type: 'string' },
+          obj: {
+            type: 'object',
+            properties: {
+              some: { type: 'string' }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  fastify.get('/', opts, () => {})
+
+  fastify.ready(err => {
+    t.error(err)
+
+    const swaggerObject = fastify.swagger()
+    t.notOk(swaggerObject.paths['/'])
+  })
+})
+
 test('cache - json', t => {
   t.plan(3)
   const fastify = Fastify()