swagger-routes-express - npm Package Compare versions

Comparing version 3.0.5 to 3.1.0

package.json

 {
   "name": "swagger-routes-express",
-  "version": "3.0.5",
+  "version": "3.1.0",
   "description": "Connect Express route controllers to restful paths using a Swagger 2 or OpenAPI 3 definition file",
@@ -58,3 +58,3 @@ "main": "src/index.js",
     "eslint-plugin-import": "^2.18.2",
-    "eslint-plugin-mocha": "^6.1.1",
+    "eslint-plugin-mocha": "^6.2.0",
     "eslint-plugin-node": "^10.0.0",
@@ -65,5 +65,5 @@ "eslint-plugin-prettier": "^3.1.1",
     "faker": "^4.1.0",
-    "husky": "^3.0.8",
+    "husky": "^3.0.9",
     "lint-staged": "^9.4.2",
-    "mocha": "^6.2.1",
+    "mocha": "^6.2.2",
     "mock-req-res": "^1.1.2",
@@ -70,0 +70,0 @@ "nyc": "^14.1.1",

README.md

@@ -14,18 +14,2 @@ # swagger-routes-express
 
-## Upgrading from Swagger Routes Express V2 to V3.
-
-These docs refer to Version 3 of Swagger Routes Express which changed the way you invoke the `connector`.
-
-### The old way
-
-```js
-const connector = require('swagger-routes-express')
-```
-
-### The new way
-
-```js
-const { connector } = require('swagger-routes-express')
-```
-
 ## Install
@@ -205,3 +189,3 @@
 
-### Your Express Server
+## Your Express Server
 
@@ -232,6 +216,8 @@ You could set up your server as follows:
 
-### Adding security middleware handlers
+## Adding security middleware handlers
 
 You can pass in a range of options, so if your swagger document defines security scopes you can pass in via a `security` option:
 
+### With scopes
+
 For example if your path has a `security` block like
@@ -264,4 +250,8 @@
 
-If your paths supply a `security` block but its `scopes` array is empty you can just use its name instead in the `security` option.
+### Without scopes
 
+If your paths supply a `security` block but its `scopes` array is empty, you can just use its name instead in the `security` option.
+
+Given:
+
 ```yml
@@ -276,3 +266,3 @@ paths:
 
-supply a `security` option like
+Supply a `security` option like:
 
@@ -287,8 +277,8 @@ ```js
 
-#### Notes
+### Notes
 
-- Only the **first** security option is used.
-- The previous version of `swagger-routes-express` used a `scopes` option but this didn't make sense for security without scopes. To preserve backwards compatibility the `scopes` option is still permitted but you'll get a deprecation warning.
+- The scopes, if supplied, are sorted alphabetically.
+- Only the **first** security option is used, the others are ignored.
 
-#### What's an Auth Middleware function?
+### What's an Auth Middleware function?
 
@@ -314,3 +304,3 @@ An Auth Middleware Function is simply an [Express Middleware function](https://expressjs.com/en/guide/using-middleware.html) that checks to see if the user making the request is allowed to do so.
 
-#### OpenAPI V3 Security Blocks
+### OpenAPI V3 Global Security Blocks
 
@@ -346,3 +336,3 @@ OpenAPI V3 allows you to define a global `security` definition as well as path specific ones. The global `security` block will be applied if there is no path specific one defined.
 
-### Adding hooks
+## Adding hooks
 
@@ -358,3 +348,3 @@ You can supply an `onCreateRoute` handler function with the options with signature
 
-The method will be one of `get`, `put`, `post`, `delete`, etc.
+The method will be one of 'get', 'post', 'patch', 'put', or 'delete'.
 
@@ -372,3 +362,3 @@ The descriptor is an array of
 
-### Mapping to nested API routes
+## Mapping to nested API routes
 
@@ -385,3 +375,3 @@ If your `./api` folder contains nested controllers such as:
 
-### Missing Route Controllers
+## Missing Route Controllers
 
@@ -392,9 +382,9 @@ If a route controller is defined as an `operationId` in swagger but there is no corresponding controller, a default `notImplemented` controller will be inserted that simply responds with a `501` error. You can also specify your own `notImplemented` controller in `options`.
 
-### Base paths
+## Base paths
 
-#### Swagger Version 2
+### Swagger Version 2
 
 For the root path `/` we check the route's `tags`. If the first tag defined for a path is `'root'` we don't inject the api basePath, otherwise we do. You can define your own `rootTag` option to override this.
 
-#### OpenAPI Version 3
+### OpenAPI Version 3
 
@@ -405,3 +395,3 @@ The OpenAPI format allows you to define both a default `servers` array, and `path` specific `servers` arrays. The `url` fields in those arrays are parsed, ignoring any absolute URLS (as they are deemed to refer to controllers external to this API Server).
 
-### Default Options
+## Default Options
 
@@ -426,6 +416,4 @@ If you don't pass in any options the defaults are:
 
-**This is new in SRE V3**
+You can generate a summary of your Swagger v2 or OpenAPI v3 API specification in the form:
 
-You can generate a summary of your Swagger v3 or OpenAPI v3 API specification in the form:
-
 ```js
@@ -448,2 +436,18 @@ {
 
+## Upgrading from Swagger Routes Express V2 to V3.
+
+These docs refer to Version 3 of Swagger Routes Express which changed the way you invoke the `connector`.
+
+### The old way
+
+```js
+const connector = require('swagger-routes-express')
+```
+
+### The new way
+
+```js
+const { connector } = require('swagger-routes-express')
+```
+
 ## Development
@@ -450,0 +454,0 @@

src/connector/connectSecurity.js

@@ -6,3 +6,3 @@ const connectSecurity = (key, options) => {
       process.emitWarning(
-        'The `scopes` option has been deprecated. Please use `securites` instead.',
+        'The `scopes` option has been deprecated. Please use `security` instead.',
         'DeprecationWarning'
@@ -9,0 +9,0 @@ )

src/extract/v2/extractPaths.js

@@ -7,16 +7,15 @@ const { METHODS } = require('../../constants')
 
-/*
-
-  Extracts all of the path data into an array of routes
-  [
-    {
-      method,
-      route, (normalised and inclues basePath if not a root route)
-      operationId,
-      security,
-      middleware
-    }
-  ]
-
-*/
+/**
+ *  Extracts all of the path data into an array of routes in the form:
+ *  [
+ *    {
+ *      method,
+ *      route, (normalised and inclues basePath if not a root route)
+ *      operationId,
+ *      security,
+ *      middleware
+ *    }
+ *  ]
+ *
+ */
 const extractPaths = ({ basePath, paths }, options = {}) => {
@@ -23,0 +22,0 @@ const {

src/extract/v3/basePath.js

 const substituteVariables = require('../../utils/substituteVariables')
 
-/*
-  given an array of servers, return a single base path.
-*/
+/**
+ *  given an array of servers, return a single base path.
+ *  @param servers — The array of servers
+ *  @param variables — a map of variable names and the values to be substituted
+ *  @returns the eventual base path
+ */
 const basePath = (servers, variables) =>
@@ -7,0 +10,0 @@ Array.isArray(servers)

src/extract/v3/extractPaths.js

@@ -6,18 +6,19 @@ const { METHODS } = require('../../constants')
 const normaliseRoute = require('../../normalise/normaliseRoute')
+const trimBase = require('../../utils/trimBase')
 const basePath = require('./basePath')
+const pathBase = require('./pathBase')
 
-/*
-
-  Extracts all of the path data into an array of routes
-  [
-    {
-      method,
-      route, (normalised and inclues basePath if not a root route)
-      operationId,
-      security,
-      middleware
-    }
-  ]
-
-*/
+/**
+ *  Extracts all of the path data into an array of routes in the form:
+ *  [
+ *    {
+ *      method,
+ *      route, (normalised and inclues basePath if not a root route)
+ *      operationId,
+ *      security,
+ *      middleware
+ *    }
+ *  ]
+ *
+ */
 const extractPaths = ({ security, servers, paths }, options = {}) => {
@@ -35,5 +36,3 @@ const {
     const pathSecurity = normaliseSecurity(opSecurity)
-    if (pathSecurity === null) {
-      return undefined
-    }
+    if (pathSecurity === null) return // the security was an empty array.
     return pathSecurity || defaultSecurity
@@ -46,9 +45,6 @@ }
       if (op) {
-        const base =
-          (op.servers ? basePath(op.servers, variables) : defaultBasePath) ||
-          /* istanbul ignore next */ ''
-        const trimmedBase = base.endsWith('/') ? base.slice(0, -1) : base
+        const base = pathBase(op.servers, variables, defaultBasePath)
         acc.push({
           method,
-          route: normaliseRoute(`${trimmedBase}${elem}`),
+          route: normaliseRoute(`${trimBase(base)}${elem}`),
           operationId: normaliseOperationId(op.operationId, apiSeparator),
@@ -55,0 +51,0 @@ security: pathSecurity(op.security, defaultSecurity),

src/normalise/v2/normaliseSecurity.js

@@ -0,8 +1,14 @@
+const keyOrScopes = require('./keyOrScopes')
+
+/**
+ *  Normalises the supplied security object into a string.
+ *  ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject
+ *
+ * @param security — The security object, or undefined
+ * @returns a string representation of the security, or undefined if the
+ *          security was undefined
+ */
 const normaliseSecurity = security =>
-  security
-    ? Object.values(security[0])[0]
-        .sort()
-        .join(',')
-    : undefined
+  security ? keyOrScopes(security[0]) : undefined
 
 module.exports = normaliseSecurity

src/normalise/v3/normaliseSecurity.js

 // ref https://swagger.io/docs/specification/authentication/
 const normaliseV2Security = require('../v2/normaliseSecurity')
 
+/**
+ *  Normalises the supplied security object into a string.
+ *
+ * @param security — The security object, or undefined
+ * @returns a string representation of the security, or undefined if the
+ *          security was undefined, or null if the security was defined
+ *          but was an empty array.
+ */
 const normaliseSecurity = security => {
@@ -10,3 +18,3 @@ if (!security) return
   const value = first[key]
-  if (value.length === 0) return key
+  if (!value.length) return key
   return normaliseV2Security(security)
@@ -13,0 +21,0 @@ }

No alert changes

Improved metrics

Total package byte prevSize

221824

increased by0.8%

Number of package files

34

increased by9.68%

Lines of code

5199

increased by0.76%

Number of lines in readme file

469

increased by0.86%

No dependency changes