swagger-routes-express - npm Package Compare versions

Comparing version 2.0.2 to 2.0.3

package.json

 {
   "name": "swagger-routes-express",
-  "version": "2.0.2",
-  "description": "Connect your Express route controllers to restful paths using your Swagger definition file",
+  "version": "2.0.3",
+  "description": "Connect your Express route controllers to restful paths using your Swagger 2 or OpenAPI 3 definition file",
   "main": "src/index.js",
@@ -28,4 +28,4 @@ "engines": {
     "prettier": "prettier --write '**/*.{js,json,md}'",
-    "test": "find ./test/unit -name '*spec.js' | NODE_PATH=. NODE_ENV=test xargs mocha --require ./test/unit/test_helper.js",
-    "test:coverage": "find ./test/unit -name '*spec.js' |  NODE_PATH=. NODE_ENV=test xargs nyc mocha --require ./test/unit/test_helper.js"
+    "test": "find ./test/unit -name '*.test.js' | NODE_PATH=. NODE_ENV=test xargs mocha --require ./test/unit/testHelper.js",
+    "test:coverage": "find ./test/unit -name '*.test.js' |  NODE_PATH=. NODE_ENV=test xargs nyc mocha --require ./test/unit/testHelper.js"
   },
@@ -46,3 +46,3 @@ "keywords": [
     "eslint-config-standard": "^12.0.0",
-    "eslint-plugin-import": "^2.16.0",
+    "eslint-plugin-import": "^2.17.0",
     "eslint-plugin-mocha": "^5.3.0",
@@ -56,6 +56,6 @@ "eslint-plugin-node": "^8.0.1",
     "lint-staged": "^8.1.5",
-    "mocha": "^6.1.2",
+    "mocha": "^6.1.3",
     "mock-req-res": "^1.0.5",
     "nyc": "^13.3.0",
-    "prettier": "^1.16.4",
+    "prettier": "^1.17.0",
     "proxyquire": "^2.1.0",
@@ -62,0 +62,0 @@ "sinon": "^7.3.1",

README.md

 # swagger-routes-express
 
-Connect your Express route controllers to restful paths using your Swagger/OpenAPI definition file
+Connect your Express route controllers to restful paths using your Swagger 2 or OpenAPI 3 definition file
 
@@ -15,2 +15,4 @@ [![Greenkeeper badge](https://badges.greenkeeper.io/davesag/swagger-routes-express.svg)](https://greenkeeper.io/)
 
+[![NPM](https://nodei.co/npm/swagger-routes-express.png)](https://nodei.co/npm/swagger-routes-express/)
+
 ## Prerequisites
@@ -27,3 +29,3 @@
 
-```
+```sh
 npm i swagger-routes-express
@@ -38,3 +40,3 @@ ```
 
-```
+```js
 const { name, version, description } = require('../../package.json')
@@ -67,12 +69,12 @@
 
-```
-swagger: "2.0"
+```yml
+swagger: '2.0'
 info:
   description: Something about the API
-  version: "1.0.0"
-  title: "Test API"
-basePath: "/api/v1"
+  version: '1.0.0'
+  title: 'Test API'
+basePath: '/api/v1'
 schemes:
-  - "https"
-  - "http"
+  - 'https'
+  - 'http'
 paths:
@@ -82,57 +84,57 @@ /:
       tags:
-        - "root"
-      summary: "Get API Version Information"
-      description: "Returns a list of the available API versions"
-      operationId: "versions"
+        - 'root'
+      summary: 'Get API Version Information'
+      description: 'Returns a list of the available API versions'
+      operationId: 'versions'
       produces:
-      - "application/json"
+        - 'application/json'
       responses:
         200:
-          description: "success"
+          description: 'success'
           schema:
-            $ref: "#/definitions/ArrayOfVersions"
+            $ref: '#/definitions/ArrayOfVersions'
   /ping:
     get:
       tags:
-        - "root"
-      summary: "Get Server Information"
-      description: "Returns information about the server"
-      operationId: "ping"
+        - 'root'
+      summary: 'Get Server Information'
+      description: 'Returns information about the server'
+      operationId: 'ping'
       produces:
-      - "application/json"
+        - 'application/json'
       responses:
         200:
-          description: "success"
+          description: 'success'
           schema:
-            $ref: "#/definitions/ServerInfo"
+            $ref: '#/definitions/ServerInfo'
 definitions:
   # see https://swagger.io/docs/specification/data-models/data-types
   APIVersion:
-    type: "object"
+    type: 'object'
     properties:
       version:
-        type: "integer"
-        format: "int64"
+        type: 'integer'
+        format: 'int64'
       path:
-        type: "string"
+        type: 'string'
   ServerInfo:
-    type: "object"
+    type: 'object'
     properties:
       name:
-        type: "string"
+        type: 'string'
       description:
-        type: "string"
+        type: 'string'
       version:
-        type: "string"
+        type: 'string'
       uptime:
-        type: "number"
+        type: 'number'
   ArrayOfVersions:
-    type: "array"
+    type: 'array'
     items:
-      $ref: "#/definitions/APIVersion"
+      $ref: '#/definitions/APIVersion'
 ```
 
-### Or as an OpenAPI Version 3 example
+### OpenAPI Version 3 example
 
-```
+```yml
 openapi: 3.0.0
@@ -205,3 +207,3 @@ info:
 
-```
+```js
 const express = require('express')
@@ -229,12 +231,29 @@ const SwaggerParser = require('swagger-parser')
 
-### Adding security 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 the following `scopes` option:
+You can pass in a range of options, so if your swagger document defines security scopes you can pass in via a `security` option:
 
+For example if your path has a `security` block like
+
+```yml
+paths:
+  /private
+    get:
+      summary: some private route
+      security:
+        - access: ['read', 'write']
+  /admin
+    get:
+      summary: some admin route
+      security:
+        - access: ['admin']
 ```
+
+Supply a `security` option as follows
+
+```js
 const options = {
-  scopes: {
-    'my-scope': correspondingMiddlewareFunction,
-    'my-other-scope': otherAuthMiddleware,
-    'admin': adminAuthMiddleware
+  security: {
+    'read-write': readWriteAuthMiddlewareFunction,
+    admin: adminAuthMiddlewareFunction
   }
@@ -244,2 +263,28 @@ }
 
+If your paths supply a `security` block but its `scopes` array is empty you can just use its name instead in the `security` option.
+
+```yml
+paths:
+  /private
+    get:
+      summary: some private route
+      security:
+        - apiKey: []
+```
+
+supply a `security` option like
+
+```js
+const options = {
+  security: {
+    apiKey: myAuthMiddlewareFunction
+  }
+}
+```
+
+#### 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.
+
 #### What's an Auth Middleware function?
@@ -253,3 +298,3 @@
 
-```
+```js
 async function correspondingMiddlewareFunction(req, res, next) {
@@ -275,3 +320,3 @@ // previously you have added a userId to req (say from an 'Authorization: Bearer token' header)
 
-```
+```js
 const onCreateRoute = (method, descriptor) => {
@@ -287,4 +332,4 @@ const [path, ...handlers] = descriptor
 
-```
-[
+```js
+;[
   path, // a string. Swagger param formats will have been converted to express route formats.
@@ -330,3 +375,3 @@ security, // a middleware function (if needed)
 
-```
+```js
 {
@@ -338,3 +383,3 @@ apiSeparator: '_',
   rootTag: 'root', // unused in OpenAPI v3 docs
-  scopes: {},
+  security: {},
   variables: {}, // unused in Swagger V2 docs
@@ -358,3 +403,3 @@ INVALID_VERSION: require('./errors').INVALID_VERSION
 
-```
+```sh
 npm run lint
@@ -361,0 +406,0 @@ ```

src/connector.js

@@ -19,4 +19,4 @@ const extractVersion = require('./extract/extractVersion')
  *    onCreateRoute
- *    rootTag = 'root'
- *    scopes = {}
+ *    rootTag = 'root' // ignored if using OpenAPI v3
+ *    security = {}
  *    variables = {}
@@ -27,6 +27,3 @@ *    INVALID_VERSION = errors.INVALID_VERSION
 const connector = (api, apiDoc, options = {}) => {
-  const opts = ({
-    INVALID_VERSION = ERRORS.INVALID_VERSION,
-    onCreateRoute
-  } = options)
+  const { INVALID_VERSION = ERRORS.INVALID_VERSION, onCreateRoute } = options
 
@@ -33,0 +30,0 @@ const version = extractVersion(apiDoc)

src/connectors/connectSecurity.js

@@ -1,6 +0,15 @@
-connectSecurity = (security, options) => {
-  const { scopes = {} } = options
-  if (security) return scopes[security]
+const connectSecurity = (key, options) => {
+  const { scopes = {}, security = {} } = options
+  if (key) {
+    if (scopes[key]) {
+      process.emitWarning(
+        'The `scopes` option has been deprecated. Please use `securites` instead.',
+        'DeprecationWarning'
+      )
+      return scopes[key]
+    }
+    return security[key]
+  }
 }
 
 module.exports = connectSecurity

src/extract/v2/extractPaths.js

 const { METHODS } = require('../../constants')
-const normaliseSecurity = require('../../normalise/normaliseSecurity')
+const normaliseSecurity = require('../../normalise/v2/normaliseSecurity')
 const normaliseOperationId = require('../../normalise/normaliseOperationId')
@@ -4,0 +4,0 @@ const normaliseRoute = require('../../normalise/normaliseRoute')

src/extract/v3/extractPaths.js

 const { METHODS } = require('../../constants')
-const normaliseSecurity = require('../../normalise/normaliseSecurity')
+const normaliseSecurity = require('../../normalise/v3/normaliseSecurity')
 const normaliseOperationId = require('../../normalise/normaliseOperationId')
@@ -4,0 +4,0 @@ const normaliseRoute = require('../../normalise/normaliseRoute')

No alert changes

Improved metrics

Total package byte prevSize

218576

increased by0.96%

Number of package files

22

increased by4.76%

Lines of code

5703

increased by0.49%

Number of lines in readme file

397

increased by12.78%

No dependency changes