- adding the ability to change swagger url (#56)

- update readme
- adding an example file
- ignore vscode files
- export routes not as a fastify plugin

.gitignore

@@ -47,3 +47,5 @@ package-lock.json
 
 static
 
+# vscode files
+.vscode/

README.md

@@ -3,7 +3,7 @@
 [![Greenkeeper badge](https://badges.greenkeeper.io/fastify/fastify-swagger.svg)](https://greenkeeper.io/)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)  [![Build Status](https://travis-ci.org/fastify/fastify-swagger.svg?branch=master)](https://travis-ci.org/fastify/fastify-swagger)
 
-[Swagger](https://swagger.io/) documentation generator for Fastify.  
+[Swagger](https://swagger.io/) documentation generator for Fastify.
 It uses the schemas you declare in your routes to generate a swagger compliant doc.
 
 <a name="install"></a>
@@ -26,6 +26,7 @@ fastify.register(require('fastify-swagger'), {
       description: 'testing the fastify swagger api',
       version: '0.1.0'
     },
+    routePrefix: '/documentation',
     host: 'localhost',
     schemes: ['http'],
     consumes: ['application/json'],
@@ -115,7 +116,7 @@ fastify.ready(err => {
   }
   ```
 
-  *All the above parameters are optional.*  
+  *All the above parameters are optional.*
   You can use all the properties of the [swagger specification](https://swagger.io/specification/), if you find anything missing, please open an issue or a pr!
 
   Example of the `fastify-swagger` usage in the `dynamic` mode is available [here](examples/dynamic.js).
@@ -142,6 +143,24 @@ If you pass `{ exposeRoute: true }` during the registration the plugin will expo
 |`'/documentation/yaml'` | the yaml object representing the api  |
 |`'/documentation/'` | the swagger ui  |
 
+
+##### Overwrite swagger url end-point
+If you would like to overwrite the `/documentation` url you can use the `routePrefix` option.
+```js
+fastify.register(require('fastify-swagger'), {
+  swagger: {
+    info: {
+      title: 'Test swagger',
+      description: 'testing the fastify swagger api',
+      version: '0.1.0'
+    },
+    ...
+  },
+  exposeRoute: true,
+  routePrefix: '/documentations'
+}
+```
+
 <a name="swagger.options"></a>
 ### swagger options
 Calling `fastify.swagger` will return to you a JSON object representing your api, if you pass `{ yaml: true }` to `fastify.swagger`, it will return you a yaml string.
@@ -158,7 +177,7 @@ Global security definitions and route level security provide documentation only.
 ### Development
 In order to start development run:
 ```
-npm i 
+npm i
 npm run prepare:swagger-ui
 ```
 

dynamic.js

@@ -27,7 +27,8 @@ module.exports = function (fastify, opts, next) {
   const security = opts.swagger.security || null
 
   if (opts.exposeRoute === true) {
-    fastify.register(require('./routes'))
+    const prefix = opts.routePrefix || '/documentation'
+    fastify.register(require('./routes'), { prefix })
   }
 
   const cache = {

examples/dynamic-overwrite-endpoint.js

@@ -0,0 +1,62 @@
+'use strict'
+
+const fastify = require('fastify')()
+
+fastify.register(require('../index'), {
+  swagger: {
+    info: {
+      title: 'Test swagger',
+      description: 'testing the fastify swagger api',
+      version: '0.1.0'
+    },
+    host: 'localhost',
+    schemes: ['http'],
+    consumes: ['application/json'],
+    produces: ['application/json']
+  },
+  exposeRoute: true,
+  routePrefix: '/swagger-docs'
+})
+
+fastify.put('/some-route/:id', {
+  schema: {
+    description: 'post some data',
+    tags: ['user', 'code'],
+    summary: 'qwerty',
+    params: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'user id'
+        }
+      }
+    },
+    body: {
+      type: 'object',
+      properties: {
+        hello: { type: 'string' },
+        obj: {
+          type: 'object',
+          properties: {
+            some: { type: 'string' }
+          }
+        }
+      }
+    },
+    response: {
+      201: {
+        description: 'Succesful response',
+        type: 'object',
+        properties: {
+          hello: { type: 'string' }
+        }
+      }
+    }
+  }
+}, (req, reply) => {})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log('listening')
+})

routes.js

@@ -1,11 +1,17 @@
 'use strict'
 
-const fp = require('fastify-plugin')
 const path = require('path')
 
 function fastifySwagger (fastify, opts, next) {
   fastify.route({
-    url: '/documentation/json',
+    url: '/',
+    method: 'GET',
+    schema: { hide: true },
+    handler: (request, reply) => reply.redirect(`.${opts.prefix}/`)
+  })
+
+  fastify.route({
+    url: '/json',
     method: 'GET',
     schema: { hide: true },
     handler: function (req, reply) {
@@ -14,7 +20,7 @@ function fastifySwagger (fastify, opts, next) {
   })
 
   fastify.route({
-    url: '/documentation/yaml',
+    url: '/yaml',
     method: 'GET',
     schema: { hide: true },
     handler: function (req, reply) {
@@ -24,20 +30,12 @@ function fastifySwagger (fastify, opts, next) {
     }
   })
 
-  fastify.route({
-    url: '/documentation',
-    method: 'GET',
-    schema: { hide: true },
-    handler: (request, reply) => reply.redirect('./documentation/')
-  })
-
   // serve swagger-ui with the help of fastify-static
   fastify.register(require('fastify-static'), {
-    root: path.join(__dirname, 'static'),
-    prefix: `/documentation/`
+    root: path.join(__dirname, 'static')
   })
 
   next()
 }
 
-module.exports = fp(fastifySwagger, '>=0.14.0')
+module.exports = fastifySwagger

static.js

@@ -35,7 +35,8 @@ module.exports = function (fastify, opts, next) {
   fastify.decorate('swagger', swagger)
 
   if (opts.exposeRoute === true) {
-    fastify.register(require('./routes'))
+    const prefix = opts.routePrefix || '/documentation'
+    fastify.register(require('./routes'), { prefix })
   }
 
   const cache = {

test/route.js

@@ -165,10 +165,9 @@ test('fastify.swagger should return a valid swagger yaml', t => {
   })
 })
 
-test('/documenatation should redirect to /documentation/', t => {
+test('/documentation should redirect to /documentation/', t => {
   t.plan(4)
   const fastify = Fastify()
-
   fastify.register(fastifySwagger, swaggerInfo)
 
   fastify.get('/', () => {})
@@ -189,7 +188,7 @@ test('/documenatation should redirect to /documentation/', t => {
   })
 })
 
-test('/documenatation/:file should send back the correct file', t => {
+test('/documentation/:file should send back the correct file', t => {
   t.plan(21)
   const fastify = Fastify()
 
@@ -284,7 +283,7 @@ test('/documenatation/:file should send back the correct file', t => {
   })
 })
 
-test('/documenatation/:file 404', t => {
+test('/documentation/:file 404', t => {
   t.plan(3)
   const fastify = Fastify()
 
@@ -311,3 +310,35 @@ test('/documenatation/:file 404', t => {
     }, payload)
   })
 })
+
+test('/documentation2/json route (overwrite)', t => {
+  t.plan(2)
+  const fastify = Fastify()
+  const swaggerInfoWithRouteOverwrite = JSON.parse(JSON.stringify(swaggerInfo))
+  swaggerInfoWithRouteOverwrite.routePrefix = '/documentation2'
+  fastify.register(fastifySwagger, swaggerInfoWithRouteOverwrite)
+
+  fastify.get('/', () => {})
+  fastify.post('/', () => {})
+  fastify.get('/example', opts1, () => {})
+  fastify.post('/example', opts2, () => {})
+  fastify.get('/parameters/:id', opts3, () => {})
+  fastify.get('/example1', opts4, () => {})
+
+  fastify.inject({
+    method: 'GET',
+    url: '/documentation2/json'
+  }, (err, res) => {
+    t.error(err)
+
+    var payload = JSON.parse(res.payload)
+
+    Swagger.validate(payload)
+      .then(function (api) {
+        t.pass('valid swagger object')
+      })
+      .catch(function (err) {
+        t.fail(err)
+      })
+  })
+})