Remove swagger-ui

MIGRATION.md

@@ -0,0 +1,94 @@
+# Migration
+
+## Migrating from version 7 to 8
+
+As of version 8 `@fastify/swagger` is only responsible for generating valid
+swagger/openapi-specifications. The new `@fastify/swagger-ui` plugin is
+responsible for serving the swagger-ui frontend.
+
+Options in version 7 of `@fastify/swagger` related to the configuration
+of the swagger-ui frontend are now options of `@fastify/swagger-ui`.
+
+The `exposeRoute` option is removed.
+
+Following are the `@fastify/swagger-ui` options:
+
+| Option             | Default          | Description                                                                                                               |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| 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.|
+
+The `baseDir` option is new and is only needed if external spec files should be
+exposed. `baseDir` option of `@fastify/swagger-ui` should be set to the same
+value as the `specification.baseDir` option of `@fastify/swagger`.
+
+### Example:
+
+before:
+```js
+const fastify = require('fastify')()
+const fastifySwagger = require('@fastify/swagger')
+
+await fastify.register(fastifySwagger, {
+  mode: 'static',
+  specification: {
+    path: './examples/example-static-specification.yaml',
+    postProcessor: function(swaggerObject) {
+      return swaggerObject
+    },
+    baseDir: '/path/to/external/spec/files/location',
+  },
+  exposeRoute: true,
+  routePrefix: '/documentation',
+  initOAuth: { },
+  uiConfig: {
+    docExpansion: 'full',
+    deepLinking: false
+  },
+  uiHooks: {
+    onRequest: function (request, reply, next) { next() },
+    preHandler: function (request, reply, next) { next() }
+  },
+  staticCSP: true,
+  transformStaticCSP: (header) => header
+})
+```
+
+after:
+```js
+const fastify = require('fastify')()
+const fastifySwagger = require('@fastify/swagger')
+const fastifySwaggerUi = require('@fastify/swagger-ui')
+
+await fastify.register(fastifySwagger, {
+  mode: 'static',
+  specification: {
+    path: './examples/example-static-specification.yaml',
+    postProcessor: function(swaggerObject) {
+      return swaggerObject
+    },
+    baseDir: '/path/to/external/spec/files/location'
+  }
+})
+
+await fastify.register(fastifySwaggerUi, {
+  baseDir: '/path/to/external/spec/files/location',
+  routePrefix: '/documentation',
+  initOAuth: { },
+  uiConfig: {
+    docExpansion: 'full',
+    deepLinking: false
+  },
+  uiHooks: {
+    onRequest: function (request, reply, next) { next() },
+    preHandler: function (request, reply, next) { next() }
+  },
+  staticCSP: true,
+  transformStaticCSP: (header) => header
+})
+```

README.md

@@ -4,7 +4,7 @@
 ![CI workflow](https://github.com/fastify/fastify-swagger/workflows/CI%20workflow/badge.svg)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
 
-A Fastify plugin for serving a [Swagger UI](https://swagger.io/tools/swagger-ui/), using [Swagger (OpenAPI v2)](https://swagger.io/specification/v2/) or [OpenAPI v3](https://swagger.io/specification) schemas automatically generated from your route schemas, or from an existing Swagger/OpenAPI schema.
+A Fastify plugin for serving [Swagger (OpenAPI v2)](https://swagger.io/specification/v2/) or [OpenAPI v3](https://swagger.io/specification) schemas, which are automatically generated from your route schemas, or from an existing Swagger/OpenAPI schema.
 
 Supports Fastify versions `4.x`.
 
@@ -14,6 +14,12 @@ Supports Fastify versions `4.x`.
 
 If you are looking for a plugin to generate routes from an existing OpenAPI schema, check out [fastify-openapi-glue](https://github.com/seriousme/fastify-openapi-glue).
 
+Following plugins serve swagger/openapi front-ends based on the swagger definitions generated by this plugin:
+
+- [@fastify/swagger-ui](https://github.com/fastify/fastify-swagger-ui)
+
+See also [the migration guide](MIGRATION.md) for migrating from `@fastify/swagger` version <= `<=7.x` to version `>=8.x`.
+
 <a name="install"></a>
 ## Install
 ```
@@ -28,7 +34,6 @@ Add it to your project with `register`, pass it some options, call the `swagger`
 const fastify = require('fastify')()
 
 await fastify.register(require('@fastify/swagger'), {
-  routePrefix: '/documentation',
   swagger: {
     info: {
       title: 'Test swagger',
@@ -66,18 +71,7 @@ await fastify.register(require('@fastify/swagger'), {
         in: 'header'
       }
     }
-  },
-  uiConfig: {
-    docExpansion: 'full',
-    deepLinking: false
-  },
-  uiHooks: {
-    onRequest: function (request, reply, next) { next() },
-    preHandler: function (request, reply, next) { next() }
-  },
-  staticCSP: true,
-  transformStaticCSP: (header) => header,
-  exposeRoute: true
+  }
 })
 
 fastify.put('/some-route/:id', {
@@ -217,31 +211,16 @@ An example of using `@fastify/swagger` with `static` mode enabled can be found [
 
  | Option             | Default          | Description                                                                                                               |
  | ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
- | exposeRoute        | false            | Exposes documentation route.                                                                                              |
  | hiddenTag          | X-HIDDEN         | Tag to control hiding of routes.                                                                                          |
  | hideUntagged       | false            | If `true` remove routes without tags from resulting Swagger/OpenAPI schema file.                                          |
  | initOAuth          | {}               | Configuration options for [Swagger UI initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).     |
  | openapi            | {}               | [OpenAPI configuration](https://swagger.io/specification/#oasObject).                                                     |
- | routePrefix         | '/documentation' | Overwrite the default Swagger UI route prefix.                                                                            |
- | staticCSP          | false            | Enable CSP header for static resources.                                                                                   |
  | stripBasePath      | true             | Strips base path from routes in docs.                                                                                     |
  | swagger            | {}               | [Swagger configuration](https://swagger.io/specification/v2/#swaggerObject).                                              |
  | transform          | null             | Transform method for the route's schema and url. [documentation](#register.options.transform).                                                                                              |
- | 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.|
  | refResolver        | {}               | Option to manage the `$ref`s of your application's schemas. Read the [`$ref` documentation](#register.options.refResolver) |
  | logLevel           | info             | Allow to define route log level.                                                                                           |
 
-If you set `exposeRoute` to `true` the plugin will expose the documentation with the following APIs:
-
-| URL                     | Description                                |
-| ----------------------- | ------------------------------------------ |
-| `'/documentation/json'` | The JSON object representing the API       |
-| `'/documentation/yaml'` | The YAML object representing the API       |
-| `'/documentation/'`     | The swagger UI                             |
-| `'/documentation/*'`    | External files that you may use in `$ref`  |
-
 <a name="register.options.transform"></a>
 #### Transform
 
@@ -685,32 +664,6 @@ There are two ways to hide a route from the Swagger UI:
 - Pass `{ hide: true }` to the schema object inside the route declaration.
 - Use the tag declared in `hiddenTag` options property inside the route declaration. Default is `X-HIDDEN`.
 
-<a name="route.uiHooks"></a>
-#### Protect your documentation routes
-
-You can protect your documentation by configuring an authentication hook.
-Here is an example using the [`@fastify/basic-auth`](https://github.com/fastify/fastify-basic-auth) plugin:
-
-```js
-await fastify.register(require('@fastify/basic-auth'), {
-  validate (username, password, req, reply, done) {
-    if (username === 'admin' && password === 'admin') {
-      done()
-    } else {
-      done(new Error('You can not access'))
-    }
-  },
-  authenticate: true
-})
-
-await fastify.register(fastifySwagger, {
-  exposeRoute: true,
-  uiHooks: {
-    onRequest: fastify.basicAuth
-  }
-})
-```
-
 <a name="function.options"></a>
 ### Swagger function options
 

examples/example-static-specification.yaml

@@ -1,10 +1,10 @@
 openapi: 3.0.0
 info:
-  description: "Test swagger specification"
-  version: "1.0.0"
-  title: "Test swagger specification"
+  description: Test swagger specification
+  version: 1.0.0
+  title: Test swagger specification
   contact:
-    email: "super.developer@gmail.com"
+    email: super.developer@gmail.com
 servers:
   - url: http://localhost:3000/
     description: Localhost (uses test data)
@@ -15,17 +15,17 @@ paths:
       tags:
         - Status
       responses:
-        200:
-          description: 'Server is alive'
+        "200":
+          description: Server is alive
           content:
             application/json:
               schema:
                 type: object
                 properties:
                   health:
-                     type: boolean
+                    type: boolean
                   date:
-                     type: string
+                    type: string
                 example:
-                 health: true 
-                 date: "2018-02-19T15:36:46.758Z"
+                  health: true
+                  date: 2018-02-19T15:36:46.758Z

examples/test-package.json

@@ -1 +1,3 @@
-{}
+{
+  "name": "test"
+}

index.d.ts

@@ -59,30 +59,6 @@ export const fastifySwagger: FastifyPluginCallback<SwaggerOptions>;
 export type SwaggerOptions = (FastifyStaticSwaggerOptions | FastifyDynamicSwaggerOptions);
 export interface FastifySwaggerOptions {
   mode?: 'static' | 'dynamic';
-  /**
-   * Overwrite the swagger url end-point
-   * @default /documentation
-   */
-  routePrefix?: string;
-  /**
-   * To expose the documentation api
-   * @default false
-   */
-  exposeRoute?: boolean;
-  /**
-   * Swagger UI Config
-   */
-  uiConfig?: FastifySwaggerUiConfigOptions
-  initOAuth?: FastifySwaggerInitOAuthOptions
-  /**
-   * CSP Config
-   */
-  staticCSP?: boolean | string | Record<string, string | string[]>
-  transformStaticCSP?: (header: string) => string
-  /**
-   * route hooks
-   */
-  uiHooks?: FastifySwaggerUiHooksOptions
 }
 
 export type FastifySwaggerUiConfigOptions = Partial<{

index.js

@@ -21,8 +21,6 @@ function fastifySwagger (fastify, opts, next) {
       return next(new Error("unsupported mode, should be one of ['static', 'dynamic']"))
     }
   }
-
-  fastify.decorate('swaggerCSP', require('./static/csp.json'))
 }
 
 module.exports = fp(fastifySwagger, {

lib/mode/dynamic.js

@@ -23,24 +23,6 @@ module.exports = function (fastify, opts, done) {
 
   const { routes, Ref } = addHook(fastify, opts)
 
-  if (opts.exposeRoute === true) {
-    const prefix = opts.routePrefix || '/documentation'
-    const uiConfig = opts.uiConfig || {}
-    const initOAuth = opts.initOAuth || {}
-    const staticCSP = opts.staticCSP
-    const transformStaticCSP = opts.transformStaticCSP
-    const logLevel = opts.logLevel
-    fastify.register(require('../routes'), {
-      prefix,
-      uiConfig,
-      initOAuth,
-      staticCSP,
-      transformStaticCSP,
-      hooks: opts.uiHooks,
-      logLevel
-    })
-  }
-
   const cache = {
     object: null,
     string: null

lib/mode/static.js

@@ -58,21 +58,6 @@ module.exports = function (fastify, opts, done) {
 
   fastify.decorate('swagger', swagger)
 
-  if (opts.exposeRoute === true) {
-    const options = {
-      prefix: opts.routePrefix || '/documentation',
-      uiConfig: opts.uiConfig || {},
-      initOAuth: opts.initOAuth || {},
-      baseDir: opts.specification.baseDir,
-      staticCSP: opts.staticCSP,
-      transformStaticCSP: opts.transformStaticCSP,
-      hooks: opts.uiHooks,
-      logLevel: opts.logLevel
-    }
-
-    fastify.register(require('../routes'), options)
-  }
-
   const cache = {
     swaggerObject: null,
     swaggerString: null