@fastify/swagger-ui - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

lib/routes.js

 'use strict'
 
 const path = require('path')
+const yaml = require('yaml')
 const fastifyStatic = require('@fastify/static')
+const rfdc = require('rfdc')()
 
@@ -95,2 +97,5 @@ // URI prefix to separate static assets for swagger UI
 
+  const hasTransformSpecificationFn = typeof opts.transformSpecification === 'function'
+  const shouldCloneSwaggerObject = opts.transformSpecificationClone ?? true
+  const transformSpecification = opts.transformSpecification
   fastify.route({
@@ -101,5 +106,13 @@ url: '/json',
     ...hooks,
-    handler: function (req, reply) {
-      reply.send(fastify.swagger())
-    }
+    handler: hasTransformSpecificationFn
+      ? shouldCloneSwaggerObject
+        ? function (req, reply) {
+          reply.send(transformSpecification(rfdc(fastify.swagger()), req, reply))
+        }
+        : function (req, reply) {
+          reply.send(transformSpecification(fastify.swagger()), req, reply)
+        }
+      : function (req, reply) {
+        reply.send(fastify.swagger())
+      }
   })
@@ -112,7 +125,19 @@
     ...hooks,
-    handler: function (req, reply) {
-      reply
-        .type('application/x-yaml')
-        .send(fastify.swagger({ yaml: true }))
-    }
+    handler: hasTransformSpecificationFn
+      ? shouldCloneSwaggerObject
+        ? function (req, reply) {
+          reply
+            .type('application/x-yaml')
+            .send(yaml.stringify(transformSpecification(rfdc(fastify.swagger()), req, reply)))
+        }
+        : function (req, reply) {
+          reply
+            .type('application/x-yaml')
+            .send(yaml.stringify(transformSpecification(fastify.swagger()), req, reply))
+        }
+      : function (req, reply) {
+        reply
+          .type('application/x-yaml')
+          .send(fastify.swagger({ yaml: true }))
+      }
   })
@@ -119,0 +144,0 @@

package.json

 {
   "name": "@fastify/swagger-ui",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Serve Swagger-ui for Fastify",
@@ -56,6 +56,5 @@ "main": "index.js",
     "standard": "^17.0.0",
-    "swagger-ui-dist": "4.14.2",
+    "swagger-ui-dist": "4.15.2",
     "tap": "^16.2.0",
-    "tsd": "^0.24.1",
-    "yaml": "^2.1.1"
+    "tsd": "^0.24.1"
   },
@@ -65,3 +64,5 @@ "dependencies": {
     "fastify-plugin": "^4.0.0",
-    "openapi-types": "^12.0.2"
+    "openapi-types": "^12.0.2",
+    "rfdc": "^1.3.0",
+    "yaml": "^2.1.3"
   },
@@ -68,0 +69,0 @@ "standard": {

README.md

@@ -38,2 +38,4 @@ # @fastify/swagger-ui
   transformStaticCSP: (header) => header,
+  transformSpecification: (swaggerObject, request, reply) => { return swaggerObject },
+  transformSpecificationClone: true
 })
@@ -103,10 +105,12 @@
  | ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
- | baseDir            | undefined        | Specify the directory where all spec files that are included in the main one using $ref will be located. By default, this is the directory where the main spec file is located. Provided value should be an absolute path without trailing slash.     |
- | initOAuth          | {}               | Configuration options for [Swagger UI initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).     |
- | routePrefix        | '/documentation' | Overwrite the default Swagger UI route prefix.                                                                            |
- | staticCSP          | false            | Enable CSP header for static resources.                                                                                   |
- | transformStaticCSP | undefined         | Synchronous function to transform CSP header for static resources if the header has been previously set.                  |
- | uiConfig           | {}               | Configuration options for [Swagger UI](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md). Must be literal values, see [#5710](https://github.com/swagger-api/swagger-ui/issues/5710).|
- | uiHooks            | {}               | Additional hooks for the documentation's routes. You can provide the `onRequest` and `preHandler` hooks with the same [route's options](https://www.fastify.io/docs/latest/Routes/#options) interface.|
- | logLevel           | info             | Allow to define route log level.|
+ | baseDir              | undefined        | Specify the directory where all spec files that are included in the main one using $ref will be located. By default, this is the directory where the main spec file is located. Provided value should be an absolute path without trailing slash.     |
+ | initOAuth            | {}               | Configuration options for [Swagger UI initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).     |
+ | routePrefix          | '/documentation' | Overwrite the default Swagger UI route prefix.                                                                            |
+ | staticCSP            | false            | Enable CSP header for static resources.                                                                                   |
+ | transformStaticCSP   | undefined        | Synchronous function to transform CSP header for static resources if the header has been previously set.                  |
+ | transformSpecification     | undefined        | Synchronous function to transform the swagger document.                                                                   |
+ | transformSpecificationClone| true             | Provide a deepcloned swaggerObject to transformSpecification                                                                    |
+ | uiConfig             | {}               | Configuration options for [Swagger UI](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md). Must be literal values, see [#5710](https://github.com/swagger-api/swagger-ui/issues/5710).                                                                                                            |
+ | uiHooks              | {}               | Additional hooks for the documentation's routes. You can provide the `onRequest` and `preHandler` hooks with the same [route's options](https://www.fastify.io/docs/latest/Routes/#options) interface.|
+ | logLevel             | info             | Allow to define route log level.                                                                                          |
 
@@ -122,2 +126,48 @@ The plugin will expose the documentation with the following APIs:
 
+#### transformSpecification
+
+There can be use cases, where you want to modify the swagger definition on request. E.g. you want to modify the server
+definition based on the hostname of the request object. In such a case you can utilize the transformSpecification-option.
+
+##### Example
+```js
+const fastify = require('fastify')()
+
+await fastify.register(require('@fastify/swagger'))
+
+await fastify.register(require('@fastify/swagger-ui'), {
+  transformSpecification: (swaggerObject, req, reply) => {
+    swaggerObject.host = req.hostname
+    return swaggerObject
+  }
+})
+```
+
+By default fastify.swagger() will be deepcloned and passed to the transformSpecification-function, as fastify.swagger()
+returns a mutatable Object. You can disable the deepcloning by setting transformSpecificationClone to false. This is useful,
+if you want to handle the deepcloning in the transformSpecification function.
+
+##### Example with caching
+```js
+const fastify = require('fastify')()
+const LRU = require('tiny-lru').lru
+const rfdc = require('rfdc')()
+
+await fastify.register(require('@fastify/swagger'))
+
+const swaggerLru = new LRU(1000)
+await fastify.register(require('@fastify/swagger-ui'), {
+  transformSpecificationClone: false,
+  transformSpecification: (swaggerObject, req, reply) => {
+    if (swaggerLru.has(req.hostname)) {
+      return swaggerLru.get(req.hostname)
+    }
+    const clonedSwaggerObject = rfdc(swaggerObject)
+    clonedSwaggerObject.host = req.hostname
+    swaggerLru.set(req.hostname, clonedSwaggerObject)
+    return clonedSwaggerObject
+  }
+})
+```
+
 <a name="license"></a>
@@ -124,0 +174,0 @@ ## License

types/index.d.ts

@@ -1,2 +0,2 @@
-import { FastifyPluginCallback, onRequestHookHandler, preHandlerHookHandler } from 'fastify';
+import { FastifyPluginCallback, FastifyReply, FastifyRequest, onRequestHookHandler, preHandlerHookHandler } from 'fastify';
 
@@ -52,2 +52,5 @@ /**
   uiHooks?: FastifySwaggerUiHooksOptions
+
+  transformSpecification?: (swaggerObject: Readonly<Record<string, any>>, request: FastifyRequest, reply: FastifyReply) => Record<string, any>
+  transformSpecificationClone?: boolean
 }
@@ -54,0 +57,0 @@

types/types.test-d.ts

@@ -1,2 +0,3 @@
-import fastify from 'fastify';
+import fastify, { FastifyReply, FastifyRequest } from 'fastify';
+import { expectType } from 'tsd';
 import fastifySwaggerUi, {
@@ -130,2 +131,12 @@ FastifySwaggerUiOptions,
   uiHooks,
-})
+})
+
+app.register(fastifySwaggerUi, {
+  transformSpecificationClone: true,
+  transformSpecification: (swaggerObj, request, reply) => {
+    expectType<FastifyRequest>(request)
+    expectType<FastifyReply>(reply)
+    expectType<Readonly<Record<string, any>>>(swaggerObj)
+    return swaggerObj
+  }
+})

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Dev dependency count

14

decreased by-6.67%

Number of package files

56

increased by1.82%

Lines of code

9775

increased by2.88%

Number of lines in readme file

174

increased by40.32%

Worsened metrics

Total package byte prevSize

4435094

decreased by-0.36%

Dependency count

5

increased by66.67%

Number of medium supply chain risk alerts

3

increased by50%

Dependency changes

• + Addedrfdc@^1.3.0

• + Addedyaml@^2.1.3

• + Addedrfdc@1.4.1(transitive)

• + Addedyaml@2.6.0(transitive)