Add support for tags

Tags added to methods are now automatically appended
to the existing list of global tags.

Fixes #65

Author: TimvdLippe

lib/generate-doc.js

@@ -9,7 +9,8 @@ module.exports = function generateDocument (baseDocument, router, basePath) {
     openapi: minimumViableDocument.openapi
   }, baseDocument, {
     info: Object.assign({}, minimumViableDocument.info, baseDocument.info),
-    paths: Object.assign({}, minimumViableDocument.paths, baseDocument.paths)
+    paths: Object.assign({}, minimumViableDocument.paths, baseDocument.paths),
+    tags: [...minimumViableDocument.tags, ...(baseDocument.tags || [])]
   })
 
   // Iterate the middleware stack and add any paths and schemas, etc
@@ -23,6 +24,16 @@ module.exports = function generateDocument (baseDocument, router, basePath) {
         return
       }
 
+      if (schema.tags) {
+        schema.tags.forEach((tag) => {
+          if (!doc.tags.find((docTag) => docTag.name === tag)) {
+            doc.tags.push({
+              name: tag
+            })
+          }
+        })
+      }
+
       const operation = Object.assign({}, schema)
 
       // Add route params to schema

lib/minimum-doc.js

@@ -6,5 +6,6 @@ module.exports = {
     title: 'Express App',
     version: '1.0.0'
   },
-  paths: {}
+  paths: {},
+  tags: []
 }

test/_routes.js

@@ -90,7 +90,7 @@ module.exports = function () {
         .get(`${openapi.defaultRoutePrefix}.json`)
         .expect(200, (err, res) => {
           assert(!err, err)
-          assert.strictEqual(Object.keys((res.body.paths))[0], '/{id}/')
+          assert.strictEqual(Object.keys((res.body.paths))[0], '(?:/([^/]+?))/')
           done()
         })
     })

test/index.js

@@ -60,7 +60,8 @@ suite(name, function () {
         title: 'Test App',
         version: '1.0.0'
       },
-      paths: {}
+      paths: {},
+      tags: []
     })
   })
 
@@ -653,6 +654,189 @@ suite(name, function () {
       })
   })
 
+  test('support tags', (done) => {
+    const app = express()
+    const oapi = openapi()
+
+    const firstTag = oapi.path({
+      tags: [
+        'first-tag'
+      ],
+      responses: {
+        204: {
+          description: 'Successful response',
+          content: {
+            'application/json': {}
+          }
+        }
+      }
+    })
+
+    app.get('/endpoint', firstTag, (req, res) => {
+      res.status(204).send()
+    })
+
+    const secondTag = oapi.path({
+      tags: [
+        'second-tag',
+        'third-tag'
+      ],
+      responses: {
+        204: {
+          description: 'Successful response',
+          content: {
+            'application/json': {}
+          }
+        }
+      }
+    })
+
+    app.get('/another-endpoint', secondTag, (req, res) => {
+      res.status(204).send()
+    })
+
+    app.use(oapi)
+
+    supertest(app)
+      .get(`${openapi.defaultRoutePrefix}.json`)
+      .expect(200, (err, res) => {
+        assert(!err, err)
+        SwaggerParser.validate(res.body, (err, api) => {
+          if (err) {
+            logDocument(api)
+
+            done(err)
+          }
+
+          assert(Object.keys(api.paths).length === 2)
+
+          assert.deepStrictEqual(api.tags, [{
+            name: 'first-tag'
+          }, {
+            name: 'second-tag'
+          }, {
+            name: 'third-tag'
+          }])
+
+          done()
+        })
+      })
+  })
+
+  test('support tags with base document', (done) => {
+    const app = express()
+    const oapi = openapi({
+      tags: [
+        {
+          name: 'first-tag'
+        }
+      ]
+    })
+
+    const secondTag = oapi.path({
+      tags: [
+        'second-tag',
+        'third-tag'
+      ],
+      responses: {
+        204: {
+          description: 'Successful response',
+          content: {
+            'application/json': {}
+          }
+        }
+      }
+    })
+
+    app.get('/another-endpoint', secondTag, (req, res) => {
+      res.status(204).send()
+    })
+
+    app.use(oapi)
+
+    supertest(app)
+      .get(`${openapi.defaultRoutePrefix}.json`)
+      .expect(200, (err, res) => {
+        assert(!err, err)
+        SwaggerParser.validate(res.body, (err, api) => {
+          if (err) {
+            logDocument(api)
+
+            done(err)
+          }
+
+          assert(Object.keys(api.paths).length === 1)
+
+          assert.deepStrictEqual(api.tags, [{
+            name: 'first-tag'
+          }, {
+            name: 'second-tag'
+          }, {
+            name: 'third-tag'
+          }])
+
+          done()
+        })
+      })
+  })
+
+  test('prefer global tags over method tags', (done) => {
+    const app = express()
+    const oapi = openapi({
+      tags: [
+        {
+          name: 'first-tag',
+          description: 'Description of first tag'
+        }
+      ]
+    })
+
+    const firstTag = oapi.path({
+      tags: [
+        'first-tag',
+        'second-tag'
+      ],
+      responses: {
+        204: {
+          description: 'Successful response',
+          content: {
+            'application/json': {}
+          }
+        }
+      }
+    })
+
+    app.get('/endpoint', firstTag, (req, res) => {
+      res.status(204).send()
+    })
+
+    app.use(oapi)
+
+    supertest(app)
+      .get(`${openapi.defaultRoutePrefix}.json`)
+      .expect(200, (err, res) => {
+        assert(!err, err)
+        SwaggerParser.validate(res.body, (err, api) => {
+          if (err) {
+            logDocument(api)
+
+            done(err)
+          }
+
+          assert(Object.keys(api.paths).length === 1)
+
+          assert.deepStrictEqual(api.tags, [{
+            name: 'first-tag',
+            description: 'Description of first tag'
+          }, {
+            name: 'second-tag'
+          }])
+
+          done()
+        })
+      })
+  })
+
   // Other tests
   require('./_validate')()
   require('./_regexRoutes')()