Initial Implementation (#1)

* modify readme.md * activate stale * modify package.json * add prepare-swagger-ui.js * change target of prepare-swagger-ui to dist add types * add swagger ui vendor extensions typings test * change standard linter ignore * first round * add missing dev dependencies * make it possible to test * remove unused imports * Apply suggestions from code review Co-authored-by: Frazer Smith <[email protected]> * remove .npmignore Co-authored-by: Frazer Smith <[email protected]>
fastify · Oct 1, 2022 · 7357acb · 7357acb
1 parent 03767de
commit 7357acb
Show file tree

Hide file tree

Showing 33 changed files with 3,227 additions and 29 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,5 @@
+# Set the default behavior, in case people don't have core.autocrlf set
+* text=auto
+
+# Require Unix line endings
+* text eol=lf
diff --git a/.github/.stale.yml → .github/stale.yml b/.github/.stale.yml → .github/stale.yml
diff --git a/.taprc b/.taprc
@@ -0,0 +1,2 @@
+files:
+  - test/**/*.test.js
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Fastify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,37 +1,121 @@
-# skeleton
+# @fastify/swagger-ui
 
-Template repository to create standardized Fastify plugins.
+[![NPM version](https://img.shields.io/npm/v/@fastify/swagger.svg?style=flat)](https://www.npmjs.com/package/@fastify/swagger)
+![CI](https://github.com/fastify/fastify-swagger-ui/workflows/CI/badge.svg)
+[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
 
-# Getting started
+A Fastify plugin for serving [Swagger UI](https://swagger.io/tools/swagger-ui/).
 
-- Click on `Use this template` above to create a new repository based on this repository.
+Supports Fastify versions `4.x`.
 
-# What's included?
+<a name="install"></a>
+## Install
+```
+npm i @fastify/swagger-ui
+```
+
+<a name="usage"></a>
+## Usage
+Add it with `@fastify/swagger` to your project with `register`, pass it some options, call the `swagger` API, and you are done!
 
-1. Github CI Actions for installing, testing your package.
-2. Github CI Actions to validate different package managers.
-3. Dependabot V2 config to automate dependency updates.
-4. Template for the GitHub App [Stale](https://github.com/apps/stale) to mark issues as stale. 
-5. Template for the GitHub App [tests-checker](https://github.com/apps/tests-checker) to check if a PR contains tests.
+```js
+const fastify = require('fastify')()
 
-# Repository structure
+await fastify.register(require('@fastify/swagger'))
 
+await fastify.register(require('fastify/swagger-ui'), {
+  routePrefix: '/documentation',
+  uiConfig: {
+    docExpansion: 'full',
+    deepLinking: false
+  },
+  uiHooks: {
+    onRequest: function (request, reply, next) { next() },
+    preHandler: function (request, reply, next) { next() }
+  },
+  staticCSP: true,
+  transformStaticCSP: (header) => header,
+})
+
+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: 'Successful response',
+        type: 'object',
+        properties: {
+          hello: { type: 'string' }
+        }
+      },
+      default: {
+        description: 'Default response',
+        type: 'object',
+        properties: {
+          foo: { type: 'string' }
+        }
+      }
+    },
+    security: [
+      {
+        "apiKey": []
+      }
+    ]
+  }
+}, (req, reply) => {})
+
+await fastify.ready()
 ```
-├── .github
-│   ├── workflows
-│   │   ├── ci.yml
-│   │   └── package-manager-ci.yml
-│   ├── .stale.yml
-│   ├── dependabot.yml
-│   └── tests_checker.yml
-│
-├── docs (Documentation)
-│   
-├── examples (Code examples)
-│
-├── test (Application tests)
-│   
-├── types (Typescript types)
-│  
-└── README.md
-```
+<a name="api"></a>
+## API
+
+<a name="register.options"></a>
+### Register options
+
+#### Options
+
+ | Option             | Default          | Description                                                                                                               |
+ | ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
+ | 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 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="license"></a>
+## License
+
+Licensed under [MIT](./LICENSE).
diff --git a/examples/collection-format.js b/examples/collection-format.js
@@ -0,0 +1,51 @@
+'use strict'
+
+const fastify = require('fastify')({
+  // Need to add a collectionFormat keyword to ajv in fastify instance
+  ajv: {
+    customOptions: {
+      keywords: ['collectionFormat']
+    }
+  }
+})
+
+fastify.register(require('@fastify/swagger'))
+fastify.register(require('../index'))
+
+fastify.route({
+  method: 'GET',
+  url: '/',
+  schema: {
+    querystring: {
+      type: 'object',
+      required: ['fields'],
+      additionalProperties: false,
+      properties: {
+        fields: {
+          type: 'array',
+          items: {
+            type: 'string'
+          },
+          minItems: 1,
+          //
+          // Note that this is an Open API version 2 configuration option.  The
+          // options changed in version 3. The plugin currently only supports
+          // version 2 of Open API.
+          //
+          // Put `collectionFormat` on the same property which you are defining
+          // as an array of values. (i.e. `collectionFormat` should be a sibling
+          // of the `type: "array"` specification.)
+          collectionFormat: 'multi'
+        }
+      }
+    }
+  },
+  handler (request, reply) {
+    reply.send(request.query.fields)
+  }
+})
+
+fastify.listen({ port: 3000 }, (err, addr) => {
+  if (err) throw err
+  console.log(`listening on ${addr}`)
+})
diff --git a/examples/dynamic-openapi.js b/examples/dynamic-openapi.js
@@ -0,0 +1,118 @@
+'use strict'
+
+const fastify = require('fastify')()
+
+fastify.register(require('@fastify/swagger'), {
+  openapi: {
+    info: {
+      title: 'Test swagger',
+      description: 'testing the fastify swagger api',
+      version: '0.1.0'
+    },
+    servers: [{
+      url: 'http://localhost'
+    }],
+    components: {
+      securitySchemes: {
+        apiKey: {
+          type: 'apiKey',
+          name: 'apiKey',
+          in: 'header'
+        }
+      }
+    }
+  },
+  hideUntagged: true
+})
+
+fastify.register(require('../index'))
+
+fastify.register(async function (fastify) {
+  fastify.put('/some-route/:id', {
+    schema: {
+      description: 'post some data',
+      tags: ['user', 'code'],
+      summary: 'qwerty',
+      security: [{ apiKey: [] }],
+      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' }
+          }
+        },
+        default: {
+          description: 'Default response',
+          type: 'object',
+          properties: {
+            foo: { type: 'string' }
+          }
+        }
+      }
+    }
+  }, (req, reply) => { reply.send({ hello: `Hello ${req.body.hello}` }) })
+
+  fastify.post('/some-route/:id', {
+    schema: {
+      description: 'post some data',
+      summary: 'qwerty',
+      security: [{ apiKey: [] }],
+      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) => { reply.send({ hello: `Hello ${req.body.hello}` }) })
+})
+
+fastify.listen({ port: 3000 }, err => {
+  if (err) throw err
+})