Rename to OpenAPI Snippets #31

Author: Erik-Wittern

.gitignore

@@ -37,4 +37,6 @@ jspm_packages
 .node_repl_history
 
 # build file:
-swaggersnippet.min.js
+dist
+
+.DS_Store

README.md

@@ -1,22 +1,22 @@
-# Swagger Snippet
-**Generates code snippets for given Swagger / Open API specification files.**
+# OpenAPI Snippet
+**Generates code snippets from Open API (previously Swagger) documents.**
 
-This package takes as input a Swagger 2.0 / OpenAPI v3.0.x specification. It translates the specification into an [HTTP Archive 1.2 request object](http://www.softwareishard.com/blog/har-12-spec/#request). It uses the [HTTP Snippet](https://github.com/Mashape/httpsnippet) library to generate code snippets for every API endpoint (URL path + HTTP method) defined in the specification in various languages & tools (`cURL`, `Node`, `Python`, `Ruby`, `Java`, `Go`, `C#`...).
+This package takes as input an OpenAPI v2.0 or v3.0.x document. It translates the document into an [HTTP Archive 1.2 request object](http://www.softwareishard.com/blog/har-12-spec/#request). It uses the [HTTP Snippet](https://github.com/Mashape/httpsnippet) library to generate code snippets for every API endpoint (URL path + HTTP method) defined in the specification in various languages & tools (`cURL`, `Node`, `Python`, `Ruby`, `Java`, `Go`, `C#`...), or for selected endpoints.
 
 ## Installation
 
 ```bash
-npm i swagger-snippet
+npm i openapi-snippet
 ```
 
-## Build Swagger Snippet (for use in browser)
-Clone the Swagger Snippet repository. Install required dependencies:
+## Build OpenAPI Snippet (for use in browser)
+Clone this repository. Install required dependencies:
 
 ```bash
 npm i
 ```
 
-Build a minified version of Swagger Snippet (`swaggersnippet.min.js`):
+Build a minified version of OpenAPI Snippet (`openapisnippet.min.js`):
 
 ```bash
 npm run build
@@ -27,44 +27,44 @@ npm run build
 ### As a module
 
 ```javascript
-const SwaggerSnippet = require('swagger-snippet')
+const OpenAPISnippet = require('openapi-snippet')
 
 // define input:
-const swagger = ... // a Swagger / Open API specification
+const openApi = ... // Open API document
 const targets = ['node_unirest', 'c'] // array of targets for code snippets. See list below...
 
 try {
   // either, get snippets for ALL endpoints:
-  const results = SwaggerSnippet.getSwaggerSnippets(swagger, targets) // results is now array of snippets, see "Output" below.
+  const results = OpenAPISnippet.getSnippets(openApi, targets) // results is now array of snippets, see "Output" below.
 
   // ...or, get snippets for a single endpoint:
-  const results2 = SwaggerSnippet.getEndpointSnippets(swagger, '/users/{user-id}/relationship', 'get', targets)
+  const results2 = OpenAPISnippet.getEndpointSnippets(openApi, '/users/{user-id}/relationship', 'get', targets)
 } catch (err) {
   // do something with potential errors...
 }
 ```
 
 ### Within the browser
 
-Include the `swaggersnippet.min.js` file created after building the the library (see above) in your HTML page:
+Include the `openapisnippet.min.js` file created after building the the library (see above) in your HTML page:
 
 ```html
-<script type="text/javascript" src="path/to/swaggersnippet.min.js"></script>
+<script type="text/javascript" src="path/to/openapisnippet.min.js"></script>
 ```
 
-Use Swagger Snippet, which now defines the global variable `SwaggerSnippet`.
+Use OpenAPI Snippet, which now defines the global variable `OpenAPISnippet`.
 
 
 ## Output
-The output for every endpoint is an object, containing the `method`, `url`, a human-readable `description`, and the corresponding `resource` - all of these values stem from the specification. In addition, within the `snippets` list, an object containing a code snippet for every chosen target is provided. As of version `0.4.0`, the snippets include exemplary payload data.
+The output for every endpoint is an object, containing the `method`, `url`, a human-readable `description`, and the corresponding `resource` - all of these values stem from the OpenAPI document. In addition, within the `snippets` list, an object containing a code snippet for every chosen target is provided. As of version `0.4.0`, the snippets include exemplary payload data.
 
-If `getSwaggerSnippets` is used, an array of the above described objects is returned.
+If `getSnippets` is used, an array of the above described objects is returned.
 
 For example:
 
-```json
+```js
 [
-  ...
+  // ...
   {
     "method": "GET",
     "url": "https://api.instagram.com/v1/users/{user-id}/relationship",
@@ -78,12 +78,12 @@ For example:
       }
     ]
   }
-  ...
+  // ...
 ]
 ```
 
 ## Targets
-Currently, swagger-snippet supports the following targets (depending on the HTTP Snippet library):
+Currently, OpenAPI Snippet supports the following targets (depending on the HTTP Snippet library):
 
 * `c_libcurl` (default)
 * `csharp_restsharp` (default)

index.js

@@ -1,28 +1,40 @@
 /**
- * swagger-snippet
- * Generate code snippets for given Swagger / Open API Specification files
+ * openapi-snippet
+ *
+ * Generates code snippets from Open API (previously Swagger) documents.
  *
  * Author: Erik Wittern
  * License: MIT
  */
 'use strict'
 
-var SwaggerToHar = require('./swagger-to-har.js')
-var HTTPSnippet = require('httpsnippet')
+const OpenAPIToHar = require('./openapi-to-har.js')
+const HTTPSnippet = require('httpsnippet')
 
-var getEndpointSnippets = function (swagger, path, method, targets, values) {
+/**
+ * Return snippets for endpoint identified using path and method in the given
+ * OpenAPI document.
+ *
+ * @param {object} openApi  OpenAPI document
+ * @param {string} path     Path identifying endpoint, e.g., '/users'
+ * @param {string} method   HTTP method identifying endpoint, e.g., 'get'
+ * @param {array} targets   List of languages to create snippets in, e.g, 
+ *                          ['cURL', 'Node']
+ * @param {object} values   Optional: Values for the query parameters if present
+ */
+const getEndpointSnippets = function (openApi, path, method, targets, values) {
   // if optional parameter is not provided, set it to empty object
   if (typeof values === 'undefined') {
     values = {}
   }
 
-  var har = SwaggerToHar.getEndpoint(swagger, path, method, values)
+  const har = OpenAPIToHar.getEndpoint(openApi, path, method, values)
 
-  var snippet = new HTTPSnippet(har)
+  const snippet = new HTTPSnippet(har)
 
-  var snippets = []
-  for (var j in targets) {
-    var target = formatTarget(targets[j])
+  const snippets = []
+  for (let j in targets) {
+    const target = formatTarget(targets[j])
     if (!target) throw new Error('Invalid target: ' + targets[j])
     snippets.push({
       id: targets[j],
@@ -40,18 +52,25 @@ var getEndpointSnippets = function (swagger, path, method, targets, values) {
   }
 }
 
-var getSwaggerSnippets = function (swagger, targets) {
-  var harList = SwaggerToHar.getAll(swagger)
+/**
+ * Return snippets for all endpoints in the given OpenAPI document.
+ * 
+ * @param {object} openApi  OpenAPI document
+ * @param {array} targets   List of languages to create snippets in, e.g, 
+ *                          ['cURL', 'Node']
+ */
+const getSnippets = function (openApi, targets) {
+  const harList = OpenAPIToHar.getAll(openApi)
 
-  var results = []
-  for (var i in harList) {
+  const results = []
+  for (let i in harList) {
     // create HTTPSnippet object:
-    var har = harList[i]
-    var snippet = new HTTPSnippet(har.har)
+    const har = harList[i]
+    const snippet = new HTTPSnippet(har.har)
 
-    var snippets = []
-    for (var j in targets) {
-      var target = formatTarget(targets[j])
+    const snippets = []
+    for (let j in targets) {
+      const target = formatTarget(targets[j])
       if (!target) throw new Error('Invalid target: ' + targets[j])
       snippets.push({
         id: targets[j],
@@ -65,12 +84,12 @@ var getSwaggerSnippets = function (swagger, targets) {
       url: har.url,
       description: har.description,
       resource: getResourceName(har.url),
-      snippets: snippets
+      snippets
     })
   }
 
   // sort results:
-  results.sort(function (a, b) {
+  results.sort((a, b) => {
     if (a.resource < b.resource) {
       return -1
     } else if (a.resource > b.resource) {
@@ -90,8 +109,8 @@ var getSwaggerSnippets = function (swagger, targets) {
  * @param  {string} b Another HTTP verb in lower case
  * @return {number}   The order instruction for the given HTTP verbs
  */
-var getMethodOrder = function (a, b) {
-  var order = ['get', 'post', 'put', 'delete', 'patch']
+const getMethodOrder = function (a, b) {
+  const order = ['get', 'post', 'put', 'delete', 'patch']
   if (order.indexOf(a) === -1) {
     return 1
   } else if (order.indexOf(b) === -1) {
@@ -109,13 +128,13 @@ var getMethodOrder = function (a, b) {
  * Determines the name of the resource exposed by the method.
  * E.g., ../users/{userId} --> users
  *
- * @param  {string} urlStr The Swagger path definition
+ * @param  {string} urlStr The OpenAPI path definition
  * @return {string}        The determined resource name
  */
-var getResourceName = function (urlStr) {
-  var pathComponents = urlStr.split('/')
-  for (var i = pathComponents.length - 1; i >= 0; i--) {
-    var cand = pathComponents[i]
+const getResourceName = function (urlStr) {
+  const pathComponents = urlStr.split('/')
+  for (let i = pathComponents.length - 1; i >= 0; i--) {
+    const cand = pathComponents[i]
     if (cand !== '' && !/^{/.test(cand)) {
       return cand
     }
@@ -129,24 +148,24 @@ var getResourceName = function (urlStr) {
  * @param  {string} targetStr String defining a target, e.g., node_request
  * @return {object}           Object with formatted target, or null
  */
-var formatTarget = function (targetStr) {
-  var language = targetStr.split('_')[0]
-  var title = capitalizeFirstLetter(language)
-  var library = targetStr.split('_')[1]
-
-  var validTargets = HTTPSnippet.availableTargets()
-  var validLanguage = false
-  var validLibrary = false
-  for (var i in validTargets) {
-    var target = validTargets[i]
+const formatTarget = function (targetStr) {
+  const language = targetStr.split('_')[0]
+  const title = capitalizeFirstLetter(language)
+  const library = targetStr.split('_')[1]
+
+  const validTargets = HTTPSnippet.availableTargets()
+  let validLanguage = false
+  let validLibrary = false
+  for (let i in validTargets) {
+    const target = validTargets[i]
     if (language === target.key) {
       validLanguage = true
       if (typeof library === 'undefined') {
         library = target.default
         validLibrary = true
       } else {
-        for (var j in target.clients) {
-          var client = target.clients[j]
+        for (let j in target.clients) {
+          const client = target.clients[j]
           if (library === client.key) {
             validLibrary = true
             break
@@ -162,32 +181,32 @@ var formatTarget = function (targetStr) {
 
   return {
     title: typeof library !== 'undefined' ? title + ' + ' + capitalizeFirstLetter(library) : title,
-    language: language,
-    library: library
+    language,
+    library
   }
 }
 
-var capitalizeFirstLetter = function (string) {
+const capitalizeFirstLetter = function (string) {
   return string.charAt(0).toUpperCase() + string.slice(1)
 }
 
 module.exports = {
-  getSwaggerSnippets: getSwaggerSnippets,
-  getEndpointSnippets: getEndpointSnippets
+  getSnippets,
+  getEndpointSnippets
 }
 
 // The if is only for when this is run from the browser
 if (typeof window !== 'undefined') {
   // grab existing namespace object, or create a blank object
   // if it doesn't exist
-  var SwaggerSnippet = window.SwaggerSnippet || {}
+  const OpenAPISnippets = window.OpenAPISnippets || {}
 
   // define that object
-  SwaggerSnippet = {
-    getSwaggerSnippets: getSwaggerSnippets,
-    getEndpointSnippets: getEndpointSnippets
+  OpenAPISnippets = {
+    getSnippets,
+    getEndpointSnippets
   }
 
   // replace/create the global namespace
-  window.SwaggerSnippet = SwaggerSnippet
+  window.OpenAPISnippets = OpenAPISnippets
 }