feat : add openapi 3 support

examples/test-package.json

@@ -1,3 +1 @@
-{
-  "version": "3.1.0"
-}
+{}

index.d.ts

@@ -1,5 +1,6 @@
 import { FastifyPlugin } from 'fastify';
 import * as SwaggerSchema from 'swagger-schema-official';
+import { OpenAPIV2, OpenAPIV3 } from 'openapi-types';
 
 declare module 'fastify' {
   interface FastifyInstance {
@@ -68,12 +69,12 @@ export interface StaticPathSpec {
 }
 
 export interface StaticDocumentSpec {
-  document: string;
+  document: OpenAPIV2.Document | OpenAPIV3.Document;
 }
 
 export interface FastifyStaticSwaggerOptions extends FastifySwaggerOptions {
   mode: 'static';
   specification: StaticPathSpec | StaticDocumentSpec;
 }
 
-export default fastifySwagger;
+export default fastifySwagger;

index.js

@@ -2,7 +2,7 @@
 
 const fp = require('fastify-plugin')
 
-const setup = { dynamic: require('./dynamic'), static: require('./static') }
+const setup = { dynamic: require('./lib/dynamic'), static: require('./lib/static') }
 
 function fastifySwagger (fastify, opts, next) {
   opts = opts || {}

lib/dynamic.js

@@ -0,0 +1,31 @@
+'use strict'
+
+const { addHook, resolveSwaggerFunction } = require('./dynamicUtil')
+
+module.exports = function (fastify, opts, done) {
+  const { routes, Ref } = addHook(fastify)
+
+  opts = Object.assign({}, {
+    exposeRoute: false,
+    hiddenTag: 'X-HIDDEN',
+    stripBasePath: true,
+    openapi: {},
+    swagger: {},
+    transform: null
+  }, opts || {})
+
+  if (opts.exposeRoute === true) {
+    const prefix = opts.routePrefix || '/documentation'
+    fastify.register(require('./routes'), { prefix })
+  }
+
+  const cache = {
+    object: null,
+    string: null
+  }
+
+  const swagger = resolveSwaggerFunction(opts, routes, Ref, cache, done)
+  fastify.decorate('swagger', swagger)
+
+  done()
+}

lib/dynamicUtil.js

@@ -0,0 +1,82 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const Ref = require('json-schema-resolver')
+
+function addHook (fastify) {
+  const routes = []
+  const sharedSchemasMap = new Map()
+
+  fastify.addHook('onRoute', (routeOptions) => {
+    routes.push(routeOptions)
+  })
+
+  fastify.addHook('onRegister', async (instance) => {
+    // we need to wait the ready event to get all the .getSchemas()
+    // otherwise it will be empty
+    // TODO: better handle for schemaId
+    // when schemaId is the same in difference instance
+    // the latter will lost
+    instance.addHook('onReady', (done) => {
+      const allSchemas = instance.getSchemas()
+      for (const schemaId of Object.keys(allSchemas)) {
+        if (!sharedSchemasMap.has(schemaId)) {
+          sharedSchemasMap.set(schemaId, allSchemas[schemaId])
+        }
+      }
+      done()
+    })
+  })
+
+  return {
+    routes,
+    Ref () {
+      const externalSchemas = Array.from(sharedSchemasMap.values())
+      // TODO: hardcoded applicationUri is not a ideal solution
+      return Ref({ clone: true, applicationUri: 'todo.com', externalSchemas })
+    }
+  }
+}
+
+function resolveSwaggerFunction (opts, routes, Ref, cache, done) {
+  let build
+  if (Object.keys(opts.openapi).length > 0 && opts.openapi.constructor === Object) {
+    build = require('./openapi')
+  } else {
+    build = require('./swagger')
+  }
+  return build(opts, routes, Ref, cache, done)
+}
+
+// The swagger standard does not accept the url param with ':'
+// so '/user/:id' is not valid.
+// This function converts the url in a swagger compliant url string
+// => '/user/{id}'
+function formatParamUrl (url) {
+  let start = url.indexOf('/:')
+  if (start === -1) return url
+
+  const end = url.indexOf('/', ++start)
+
+  if (end === -1) {
+    return url.slice(0, start) + '{' + url.slice(++start) + '}'
+  } else {
+    return formatParamUrl(url.slice(0, start) + '{' + url.slice(++start, end) + '}' + url.slice(end))
+  }
+}
+
+function readPackageJson (done) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json')))
+  } catch (err) {
+    return done(err)
+  }
+}
+
+module.exports = {
+  addHook,
+  resolveSwaggerFunction,
+  formatParamUrl,
+  readPackageJson
+}

lib/openapi.js

@@ -0,0 +1,200 @@
+'use strict'
+
+const yaml = require('js-yaml')
+const { formatParamUrl, readPackageJson } = require('./dynamicUtil')
+const { getBodyParams, getCommonParams, generateResponse, stripBasePathByServers } = require('./openapiUtil')
+
+// TODO: refactor for readability, reference in below
+// https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two
+// https://www.informit.com/articles/article.aspx?p=1398607
+module.exports = function (opts, routes, Ref, cache, done) {
+  let ref
+
+  const info = opts.openapi.info || null
+  const servers = opts.openapi.servers || null
+  const components = opts.openapi.components || null
+  const tags = opts.openapi.tags || null
+  const externalDocs = opts.openapi.externalDocs || null
+
+  const stripBasePath = opts.stripBasePath
+  const transform = opts.transform
+  const hiddenTag = opts.hiddenTag
+  const extensions = []
+
+  for (const [key, value] of Object.entries(opts.openapi)) {
+    if (key.startsWith('x-')) {
+      extensions.push([key, value])
+    }
+  }
+
+  return function (opts) {
+    if (opts && opts.yaml) {
+      if (cache.string) return cache.string
+    } else {
+      if (cache.object) return cache.object
+    }
+
+    const openapiObject = {}
+    const pkg = readPackageJson(done)
+
+    // Base Openapi info
+    // this info is displayed in the swagger file
+    // in the same order as here
+    openapiObject.openapi = '3.0.3'
+    if (info) {
+      openapiObject.info = info
+    } else {
+      openapiObject.info = {
+        version: pkg.version || '1.0.0',
+        title: pkg.name || ''
+      }
+    }
+    if (servers) {
+      openapiObject.servers = servers
+    }
+    if (components) {
+      openapiObject.components = Object.assign({}, components, { schemas: Object.assign({}, components.schemas) })
+    } else {
+      openapiObject.components = { schemas: {} }
+    }
+    if (tags) {
+      openapiObject.tags = tags
+    }
+    if (externalDocs) {
+      openapiObject.externalDocs = externalDocs
+    }
+
+    for (const [key, value] of extensions) {
+      openapiObject[key] = value
+    }
+
+    ref = Ref()
+    openapiObject.components.schemas = {
+      ...openapiObject.components.schemas,
+      ...(ref.definitions().definitions)
+    }
+
+    // Swagger doesn't accept $id on /definitions schemas.
+    // The $ids are needed by Ref() to check the URI so we need
+    // to remove them at the end of the process
+    Object.values(openapiObject.components.schemas)
+      .forEach(_ => { delete _.$id })
+
+    openapiObject.paths = {}
+
+    for (const route of routes) {
+      const schema = transform
+        ? transform(route.schema)
+        : route.schema
+
+      if (schema && schema.hide) {
+        continue
+      }
+
+      if (schema && schema.tags && schema.tags.includes(hiddenTag)) {
+        continue
+      }
+
+      const path = stripBasePath
+        ? stripBasePathByServers(route.url, openapiObject.servers)
+        : route.url
+      const url = formatParamUrl(path)
+
+      const swaggerRoute = openapiObject.paths[url] || {}
+
+      const swaggerMethod = {}
+      const parameters = []
+
+      // route.method should be either a String, like 'POST', or an Array of Strings, like ['POST','PUT','PATCH']
+      const methods = typeof route.method === 'string' ? [route.method] : route.method
+
+      for (const method of methods) {
+        swaggerRoute[method.toLowerCase()] = swaggerMethod
+      }
+
+      // All the data the user can give us, is via the schema object
+      if (schema) {
+        // the resulting schema will be in this order
+        if (schema.operationId) {
+          swaggerMethod.operationId = schema.operationId
+        }
+
+        if (schema.tags) {
+          swaggerMethod.tags = schema.tags
+        }
+
+        if (schema.summary) {
+          swaggerMethod.summary = schema.summary
+        }
+
+        if (schema.description) {
+          swaggerMethod.description = schema.description
+        }
+
+        if (schema.externalDocs) {
+          swaggerMethod.externalDocs = schema.externalDocs
+        }
+
+        if (schema.querystring) {
+          getCommonParams('query', parameters, schema.querystring, ref, openapiObject.components.schemas)
+        }
+
+        if (schema.body) {
+          swaggerMethod.requestBody = {
+            content: {}
+          }
+          getBodyParams(swaggerMethod.requestBody.content, schema.body, schema.consumes, ref)
+        }
+
+        if (schema.params) {
+          getCommonParams('path', parameters, schema.params, ref, openapiObject.components.schemas)
+        }
+
+        if (schema.headers) {
+          getCommonParams('header', parameters, schema.headers, ref, openapiObject.components.schemas)
+        }
+
+        // TODO: need to documentation, we treat it same as the querystring
+        // fastify do not support cookies schema in first place
+        if (schema.cookies) {
+          getCommonParams('cookie', parameters, schema.cookies, ref, openapiObject.components.schemas)
+        }
+
+        if (parameters.length) {
+          swaggerMethod.parameters = parameters
+        }
+
+        if (schema.deprecated) {
+          swaggerMethod.deprecated = schema.deprecated
+        }
+
+        if (schema.security) {
+          swaggerMethod.security = schema.security
+        }
+
+        if (schema.servers) {
+          swaggerMethod.servers = schema.servers
+        }
+
+        for (const key of Object.keys(schema)) {
+          if (key.startsWith('x-')) {
+            swaggerMethod[key] = schema[key]
+          }
+        }
+      }
+
+      swaggerMethod.responses = generateResponse(schema ? schema.response : null, schema ? schema.produces : null, ref)
+
+      openapiObject.paths[url] = swaggerRoute
+    }
+
+    if (opts && opts.yaml) {
+      const openapiString = yaml.safeDump(openapiObject, { skipInvalid: true })
+      cache.string = openapiString
+      return openapiString
+    }
+
+    cache.object = openapiObject
+    return openapiObject
+  }
+}