fastify-swagger - npm Package Compare versions

Comparing version 4.9.1 to 4.10.0

examples/dynamic-swagger.js

@@ -28,2 +28,21 @@ 'use strict'
 
+fastify.addSchema({
+  $id: 'user',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'user id'
+    }
+  }
+})
+
+fastify.addSchema({
+  $id: 'some',
+  type: 'object',
+  properties: {
+    some: { type: 'string' }
+  }
+})
+
 fastify.put('/some-route/:id', {
@@ -35,11 +54,3 @@ schema: {
     security: [{ apiKey: [] }],
-    params: {
-      type: 'object',
-      properties: {
-        id: {
-          type: 'string',
-          description: 'user id'
-        }
-      }
-    },
+    params: { $ref: 'user#' },
     body: {
@@ -49,8 +60,3 @@ type: 'object',
         hello: { type: 'string' },
-        obj: {
-          type: 'object',
-          properties: {
-            some: { type: 'string' }
-          }
-        }
+        obj: { $ref: 'some#' }
       }
@@ -75,11 +81,3 @@ },
     security: [{ apiKey: [] }],
-    params: {
-      type: 'object',
-      properties: {
-        id: {
-          type: 'string',
-          description: 'user id'
-        }
-      }
-    },
+    params: { $ref: 'user#' },
     body: {
@@ -89,8 +87,3 @@ type: 'object',
         hello: { type: 'string' },
-        obj: {
-          type: 'object',
-          properties: {
-            some: { type: 'string' }
-          }
-        }
+        obj: { $ref: 'some#' }
       }
@@ -97,0 +90,0 @@ },

lib/mode/dynamic.js

@@ -6,4 +6,2 @@ 'use strict'
 module.exports = function (fastify, opts, done) {
-  const { routes, Ref } = addHook(fastify)
-
   opts = Object.assign({}, {
@@ -16,5 +14,15 @@ exposeRoute: false,
     swagger: {},
-    transform: null
+    transform: null,
+    refResolver: {
+      buildLocalReference (json, baseUri, fragment, i) {
+        if (!json.title && json.$id) {
+          json.title = json.$id
+        }
+        return `def-${i}`
+      }
+    }
   }, opts)
 
+  const { routes, Ref } = addHook(fastify, opts)
+
   if (opts.exposeRoute === true) {
@@ -21,0 +29,0 @@ const prefix = opts.routePrefix || '/documentation'

lib/util/common.js

@@ -9,3 +9,3 @@ 'use strict'
 
-function addHook (fastify) {
+function addHook (fastify, pluginOptions) {
   const routes = []
@@ -39,4 +39,7 @@ const sharedSchemasMap = new Map()
       const externalSchemas = Array.from(sharedSchemasMap.values())
-      // TODO: hardcoded applicationUri is not a ideal solution
-      return Ref({ clone: true, applicationUri: 'todo.com', externalSchemas })
+      return Ref(Object.assign(
+        { applicationUri: 'todo.com' },
+        pluginOptions.refResolver,
+        { clone: true, externalSchemas })
+      )
     }
@@ -43,0 +46,0 @@ }

package.json

 {
   "name": "fastify-swagger",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "description": "Serve Swagger/OpenAPI documentation for Fastify, supporting dynamic generation",
@@ -56,3 +56,3 @@ "main": "index.js",
     "js-yaml": "^4.0.0",
-    "json-schema-resolver": "^1.2.0",
+    "json-schema-resolver": "^1.3.0",
     "openapi-types": "^9.1.0"
@@ -59,0 +59,0 @@ },

README.md

@@ -214,3 +214,3 @@ # fastify-swagger
  | openapi            | {}               | [OpenAPI configuration](https://swagger.io/specification/#oasObject).                                                     |
- | routePrefix        | '/documentation' | Overwrite the default Swagger UI route prefix.                                                                            |
+ | routePrefix         | '/documentation' | Overwrite the default Swagger UI route prefix.                                                                            |
  | staticCSP          | false            | Enable CSP header for static resources.                                                                                   |
@@ -220,4 +220,5 @@ | stripBasePath      | true             | Strips base path from routes in docs.                                                                                     |
  | transform          | null             | Transform method for schema.                                                                                              |
- | 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).|
+ | 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).|
+ | refResolver        | {}               | Option to manage the `$ref`s of your application's schemas. Read the [`$ref` documentation](#register.options.refResolver) |
 
@@ -260,2 +261,28 @@ If you set `exposeRoute` to `true` the plugin will expose the documentation with the following APIs:
 
+<a name="register.options.refResolver"></a>
+#### Managing your `$ref`s
+
+When this plugin is configured as `dynamic` mode, it will resolve all `$ref`s in your application's schemas.
+This process will create an new in-line schema that is going to reference itself.
+
+This logic step is done to make sure that the generated documentation is valid, otherwise the Swagger UI will try to fetch the schemas from the server or the network and fail.
+
+By default, this option will resolve all `$ref`s renaming them to `def-${counter}`, but your view models keep the original `$id` naming thanks to the [`title` parameter](https://swagger.io/docs/specification/2-0/basic-structure/#metadata).
+
+To customize this logic you can pass a `refResolver` option to the plugin:
+
+```js
+fastify.register(require('fastify-swagger'), {
+  swagger: { ... },
+  ...
+  refResolver: {
+    buildLocalReference (json, baseUri, fragment, i) {
+      return json.$id || `my-fragment-${i}`
+    }
+  }
+}
+```
+
+To deep down the `buildLocalReference` arguments, you may read the [documentation](https://github.com/Eomm/json-schema-resolver#usage-resolve-one-schema-against-external-schemas).
+
 <a name="route.options"></a>
@@ -643,4 +670,7 @@ ### Route options
 
-<a name="development"></a>
-### Development
+<a name="usage"></a>
+## `$id` and `$ref` usage
+
+
+## Development
 In order to start development run:
@@ -654,7 +684,10 @@ ```
 
-#### How it works under the hood
+### How it works under the hood
 
 `fastify-static` serves `swagger-ui` static files, then calls `/docs/json` to get the Swagger file and render it.
 
-<a name="acknowledgements"></a>
+#### How to work with $refs
+
+The `/docs/json` endpoint in dynamic mode produces a single `swagger.json` file resolving all your
+
 ## Acknowledgements
@@ -661,0 +694,0 @@

test/spec/openapi/schema.js

@@ -311,3 +311,23 @@ 'use strict'
   const api = await Swagger.validate(swaggerObject)
-  t.same(api.components.schemas['def-0'], schema)
+  t.match(api.components.schemas['def-0'], schema)
 })
+
+test('support global schema reference with title', async t => {
+  const schema = {
+    title: 'schema view title',
+    type: 'object',
+    properties: {
+      hello: { type: 'string' }
+    },
+    required: ['hello']
+  }
+  const fastify = Fastify()
+  fastify.register(fastifySwagger, { openapi: true, routePrefix: '/docs', exposeRoute: true })
+  fastify.addSchema({ ...schema, $id: 'requiredUniqueSchema' })
+  fastify.get('/', { schema: { query: { $ref: 'requiredUniqueSchema' } } }, () => {})
+  await fastify.ready()
+
+  const swaggerObject = fastify.swagger()
+  const api = await Swagger.validate(swaggerObject)
+  t.match(api.components.schemas['def-0'], schema)
+})

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

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

Total package byte prevSize

10797734

increased by0.02%

Lines of code

14449

increased by0.14%

Number of lines in readme file

698

increased by4.96%

Dependency changes

• Updatedjson-schema-resolver@^1.3.0