Merge pull request #2 from ibm-developer/development

Initial load into master

Author: cvignola

.eslintignore

@@ -0,0 +1,6 @@
+node_modules/
+# If eslint goes into this dir it will read package.json as a config file
+# We either rename the package.json template, or we don't lint this dir
+generators/app/templates/
+generators/core/templates/
+coverage/

.eslintrc.yml

@@ -0,0 +1,14 @@
+env:
+  node: true
+  es6: true
+  mocha: true
+
+rules:
+  strict: 2
+  no-var: 2
+  no-console: 0
+  indent: [2, 2, { "SwitchCase": 1}]
+
+extends: eslint:recommended
+
+plugins: [ejs]

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+coverage/
+.nyc_output/
+.vscode/
+.idea
+*.lock

.travis.yml

@@ -0,0 +1,23 @@
+language: node_js
+
+node_js:
+- '8'
+
+script: npm test && npm run coveralls && ./npm_patch.sh
+
+branches:
+  only:
+    - development
+    - master
+
+notifications:
+  slack: 
+    rooms:
+      - $SLACK_ARF_DEVOPS
+
+deploy:
+  provider: npm
+  email: $NPM_EMAIL
+  api_key: $NPM_TOKEN
+  on:
+    branch: master

README.md

@@ -1 +1,82 @@
-# openapi-support
+# ibm-openapi-support
+
+This module is a utility to make the process of loading and parsing documents in the OpenAPI (swagger) format a simple task. The primary use case for this is code generation where a swagger document is loaded, parsed and then relavent data structures for building api endpoints are made available.
+
+## Quick start
+
+Swaggerize contains two modules, index.js and utils.js. They are described below: 
+
+* __utils.loadAsync__: This utility method is used for loading a swagger document from a file path or url. The method takes two arguments and returns a dictionary with two keys, _**loaded**_ and _**parsed**_. The _**loaded**_ key contains a javascript object containing the original document. The _**parsed**_ key contains the a dictionary with parsed swagger elements. The arguments to __loadAsync__:
+	- path or url to the openApi document.
+	- in-memory filesystem object; only required if loading from a file path.
+
+```javascript
+var swaggerize = require('ibm-openapi-support')
+var loadedApi
+var parsedSwagger
+
+var memFs = require('mem-fs')
+var editor = require('mem-fs-editor')
+var store = memFs.create()
+var fs = editor.create(store)
+
+return utils.loadAsync('../resources/person_dino.json', fs)
+  .then(loaded => swaggerize.parse(loaded, formatters))
+  .then(response => {
+    loadedApi = response.loaded
+    parsedSwagger = response.parsed
+  })
+```
+
+* __index.parse__: This method is used to parse the swagger conument and build a dictionary of structures that contain the routes, resources and basepath required for generating API code. The parse method will use the supplied formatters to modify the path and the resource. This method takes two parameters:
+	- stringified OpenApi (swagger) document.
+	- formatters dictionary: This contains formatters for the path _**pathFormatter**_ and for the resource _**resourceFormatter**_ The formatters take a path parameter and return a string.
+
+```javascript
+var swaggerize = require('ibm-openapi-support')
+var swaggerizeUtils = require('ibm-openapi-support/utils')
+
+var swaggerDocument = 'your OpenApi (swagger) document goes here' 
+
+function reformatPathToNodeExpress (thepath) {
+  // take a swagger path and convert the parameters to express format.
+  // i.e. convert "/path/to/{param1}/{param2}" to "/path/to/:param1/:param2"
+  var newPath = thepath.replace(/{/g, ':')
+  return newPath.replace(/}/g, '')
+}
+
+function resourceNameFromPath (thePath) {
+  // grab the first valid element of a path (or partial path) and return it.
+  return thePath.match(/^\/*([^/]+)/)[1]
+}
+
+this.parsedSwagger = undefined;
+var formatters = {
+  'pathFormatter': helpers.reformatPathToNodeExpress,
+  'resourceFormatter': helpers.resourceNameFromPath
+}
+
+if (swaggerDocument !== undefined) {
+  return swaggerize.parse(swaggerDocument, formatters)
+  .then(response => {
+    this.loadedApi = response.loaded
+    this.parsedSwagger = response.parsed
+  })
+  .catch(err => {
+    err.message = 'failed to parse document ' + err.message
+    throw err
+  })
+}
+
+if (this.parsedSwagger) {
+  Object.keys(this.parsedSwagger.resources).forEach(function(resource) {
+    var context = {
+      'resource': resource,
+      'routes': this.parsedSwagger.resources[resource],
+      'basepath': this.parsedSwagger.basepath
+    }
+    this.fs.copyTpl(this.templatePath('fromswagger/routers/router.js'), this.destinationPath(`server/routers/${resource}.js`), context)
+    this.fs.copyTpl(this.templatePath('test/resource.js'), this.destinationPath(`test/${resource}.js`), context)
+  }.bind(this))
+}
+```

coverage.lcov

@@ -0,0 +1,153 @@
+/*
+ * Copyright IBM Corporation 2017
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+'use strict'
+let debug = require('debug')('arf:swaggerize:index')
+let utils = require('./utils')
+let swaggerParser = require('swagger-parser')
+let builderUtils = require('swaggerize-routes/lib/utils')
+
+function ensureValidAsync (loadedSwagger) {
+  debug('in ensureValidAsync')
+  return swaggerParser.validate(loadedSwagger)
+    .catch(function (err) {
+      debug(err)
+      throw new Error('does not conform to swagger specification')
+    })
+}
+
+function parseSwagger (api, formatters) {
+  debug('in parseSwagger')
+  // walk the api, extract the schemas from the definitions, the parameters and the responses.
+  let resources = {}
+  let refs = []
+  let basePath = api.basePath || undefined
+
+  formatters = formatters === undefined ? {} : formatters
+
+  let pathFormatter = formatters['pathFormatter'] || function (path) { return path }
+  let resourceFormatter = formatters['resourceFormatter'] || function (route) { return route }
+
+  Object.keys(api.paths).forEach(function (path) {
+    let resource = resourceFormatter(path)
+
+    debug('path:', path, 'becomes resource: "' + resource + '" with route: "' + pathFormatter(path) + '"')
+    // for each path, walk the method verbs
+    builderUtils.verbs.forEach(function (verb) {
+      if (api.paths[path][verb]) {
+        if (!resources[resource]) {
+          resources[resource] = []
+        }
+
+        debug('parsing verb:', verb)
+        // save the method and the path in the resources list.
+        resources[resource].push({method: verb, route: pathFormatter(path)})
+        // process the parameters
+        if (api.paths[path][verb].parameters) {
+          let parameters = api.paths[path][verb].parameters
+
+          parameters.forEach(function (parameter) {
+            if (parameter.schema) {
+              if (parameter.schema.$ref) {
+                // handle the schema ref
+                let ref = utils.getRefName(parameter.schema.$ref)
+                refs[ref] = api.definitions[ref]
+              } else if (parameter.schema.items) {
+                // handle array of schema items
+                if (parameter.schema.items.$ref) {
+                  let ref = utils.getRefName(parameter.schema.items.$ref)
+                  // handle the schema ref
+                  refs[ref] = api.definitions[ref]
+                }
+              }
+            }
+          })
+        }
+
+        // process the responses. 200 and default are probably the only ones that make any sense.
+        ['200', 'default'].forEach(function (responseType) {
+          if (api.paths[path][verb].responses && api.paths[path][verb].responses[responseType]) {
+            let responses = api.paths[path][verb].responses
+            if (responses[responseType] && responses[responseType].schema) {
+              let ref
+              if (responses[responseType].schema.$ref) {
+                // handle the schema ref
+                ref = utils.getRefName(responses[responseType].schema.$ref)
+                refs[ref] = api.definitions[ref]
+              } else if (responses[responseType].schema.type && responses[responseType].schema.type === 'array') {
+                if (responses[responseType].schema.items && responses[responseType].schema.items.$ref) {
+                  ref = utils.getRefName(responses[responseType].schema.items.$ref)
+                  refs[ref] = api.definitions[ref]
+                  if (responses[responseType].schema.items) {
+                    // handle array of schema items
+                    if (responses[responseType].schema.items.$ref) {
+                      // handle the schema ref
+                      ref = utils.getRefName(responses[responseType].schema.items.$ref)
+                      refs[ref] = api.definitions[ref]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        })
+      }
+    })
+  })
+
+  let foundNewRef
+  do {
+    foundNewRef = false
+    // now parse the schemas for child references.
+    Object.keys(refs).forEach(function (schema) {
+      if (refs[schema] && refs[schema].properties) {
+        let properties = refs[schema].properties
+        Object.keys(properties).forEach(function (property) {
+          let name
+          if (properties[property].$ref) {
+            // this property contains a definition reference.
+            name = utils.getRefName(properties[property].$ref)
+            if (!refs[name]) {
+              refs[name] = api.definitions[name]
+              foundNewRef = true
+            }
+          } else if (properties[property].items && properties[property].items.$ref) {
+            // this property contains a definition reference.
+            name = utils.getRefName(properties[property].items.$ref)
+            if (!refs[name]) {
+              refs[name] = api.definitions[name]
+              foundNewRef = true
+            }
+          }
+        })
+      }
+    })
+  } while (foundNewRef)
+
+  let parsed = {basepath: basePath, resources: resources, refs: refs}
+  return parsed
+}
+
+exports.parse = function (swaggerStr, formatters) {
+  debug('in parse')
+  let loaded = JSON.parse(swaggerStr)
+  return ensureValidAsync(loaded)
+    .then(function () {
+      debug('successfully validated against schema')
+      // restore the original swagger as the call to ensureValidAsync modifies the original loaded object.
+      loaded = JSON.parse(swaggerStr)
+      return { loaded: loaded, parsed: parseSwagger(loaded, formatters) }
+    })
+}

index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+set -ev
+
+if [[ "${TRAVIS_PULL_REQUEST}" = "false" ]]; then
+    echo "Not a Pull Request build. Proceeding."
+
+    # On development branch, we want to auto increment package patch version number
+    # and push commit back to repo
+    if [[ "${TRAVIS_BRANCH}" = "development" ]]; then
+        echo "On development branch"
+        echo "Commit message: ${TRAVIS_COMMIT_MESSAGE}"
+
+        if [[ "${TRAVIS_COMMIT_MESSAGE}" ==  "[Travis - npm version patch]"* ]]; then
+            echo "This is a version increment commit. Doing nothing."
+        else
+            echo "Incrementing patch version and pushing back to repo."
+
+            echo "commit: ${TRAVIS_COMMIT}"
+            USER_EMAIL=$(git --no-pager show -s --format='%ae' "${TRAVIS_COMMIT}")
+            USER_NAME=$(git --no-pager show -s --format='%an' "${TRAVIS_COMMIT}")
+            echo "user email: ${USER_EMAIL}"
+            echo "user name: ${USER_NAME}"
+            git config user.email "${USER_EMAIL}"
+            git config user.name "${USER_NAME}"
+
+            git checkout -- .
+            git checkout -b increment-patch-version
+            npm version patch -m "[Travis - npm version patch] Increment package version to %s"
+
+            git branch --set-upstream-to origin/development
+            git push $GITHUB_URL_SECURED HEAD:development
+            git push $GITHUB_URL_SECURED HEAD:development --tags
+        fi
+    fi
+else
+    echo "This is a Pull Request build. Doing nothing."
+fi