Support URL Objects

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+PRs are always welcome, and we'll be happy to merge them if the test suite passes.
+
+To run the entire test suite would take a long time, so we've broken it down into various groups:
+
+``` shell
+TEST_TARGET=lint make test
+TEST_TARGET=unit make test
+TEST_TARGET=e2e make test
+TEST_TARGET=cov make test
+```
+
+All of these will be run by Travis, but you could save the ice caps from melting a little by running at least `unit` and `e2e` before you push.
+
+Our sole requirement is that organizations that want to extend API-Flow to support their format write both a parser and a serializer, and not simply a serializer.

README.md

@@ -4,60 +4,72 @@
 
 A flow written in ES6 using Immutable to convert between API description formats (Swagger, etc.) and other programs such as cURL command lines.
 
-## What formats are supported and what will be in the future
+## Format Support
+
 We currently support:
-- `Swagger v2.0 (in/out)`
-- `RAML v1.0 (in/out)`
-- `Postman Collection v2.0 (in/out)`
-- `Paw v3.1 (in/out)`
+
+- Swagger v2.0 (in/out)
+- RAML v1.0 (in/out)
+- Postman Collection v2.0 (in/out)
+- Paw v3.1 (in/out)
 
 We intend to support:
-- `Swagger v3.0`
-- `RAML v0.8`
-- `Postman Collection v1.0`
-- `Postman Dump v1.0`
-- `Insomnia v3.0`
-- `Api-Blueprint`
+
+- Swagger v3.0
+- RAML v0.8
+- Postman Collection v1.0
+- Postman Dump v1.0
+- Insomnia v3.0
+- API Blueprint
 - and many more.
 
 ## Installation
-### from a cloned repository
 
-just run
+You can install this library in two different ways.
+
+
+### Install via NPM/Yarn
+
+```shell
+$ yarn add api-flow
+# or
+$ npm install api-flow
+```
+
+### Install from source
+
+Just run:
 
 ```sh
 git clone https://github.com/luckymarmot/API-Flow.git
 cd API-Flow
-make install
+yarn install
+make
 ```
 
-This will install the node module dependencies
-
-## Building the different libraries
-### node, web, and webworker
-
-run the following command to build API-Flow for the different environments that you need
+This will install the node module dependencies, but you will need to build API-Flow for the different [environments](src/environments) that you need:
 
 ```sh
 # use TARGET="node" if you only want the node library
 make runners TARGET="node web webworker"
 ```
 
-### Paw
-
-You can use the following command to add the different extensions to Paw
+You can use the following command to compile different extensions.
 
 ```sh
 # use TARGET="swagger" if you only want the swagger bindings
 make transfer TARGET="swagger raml1 postman2"
 ```
 
-## Using the npm module
-### as a standard library
+## Usage
+
+### Standard Library
 
 ```js
-const ApiFlow = require('api-flow'); // if from npm
-const ApiFlow = require('./dist/node/api-flow.js'); // if from `make runners TARGET="node"`
+const ApiFlow = require('api-flow').default; // if from yarn/npm
+const ApiFlow = require('./dist/node/api-flow.js').default; // if from `make runners TARGET="node"`
+
+const path = require('path');
 
 const options = {
     source: {
@@ -80,22 +92,19 @@ promise.then((data) => {
 })
 ```
 
-### Using as a CLI (coming soon)
-```sh
-node ./bin/api-flow.js some_swagger.json -f swagger -t raml > converted.yml
-```
-
 ### User Interface
 
 API-Flow is one of the main components of [Console.REST](https://github.com/luckymarmot/console-rest). If you're an API user, you can easily use [https://console.rest/](https://console.rest/) to convert API description files. If you're an API provider, you can add a button to your API docs to let your users open and play with your API in client apps including Paw or Postman.
 
 ## Contributing
 
-PRs are welcomed!
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for more tips on testing and contributing.
+
 Our sole requirement is that organizations that want to extend API-Flow to support their format write both a parser and a serializer, and not simply a serializer.
 
 ## Documentation
-You can find more information about the internal structure of API-Flow in [src](https://github.com/luckymarmot/API-Flow/tree/develop/src). We've also created a set of templates to help speed up the extension process: [loader](https://github.com/luckymarmot/API-Flow/tree/develop/src/loaders/template/v1.0), [parser](https://github.com/luckymarmot/API-Flow/tree/develop/src/parsers/template/v1.0/), and [environment](https://github.com/luckymarmot/API-Flow/tree/develop/src/environments/template)
+
+You can find more information about the internal structure of API-Flow in [src](src). We've also created a set of templates to help speed up the extension process: [loader](src/loaders/template/v1.0), [parser](src/parsers/template/v1.0/), and [environment](src/environments/template)
 
 ## License
 
@@ -104,4 +113,4 @@ Copyright © 2016 Paw Inc.
 
 ## Contributors
 
-See [Contributors](https://github.com/luckymarmot/API-Flow/graphs/contributors).
+See [Contributors](https://github.com/JonathanMontane/API-Flow/graphs/contributors).

configs/node/api-flow-config.js

@@ -2,34 +2,34 @@ import Environment from '../../src/environments/node/Environment'
 
 import SwaggerLoader from '../../src/loaders/swagger/Loader'
 import RAMLLoader from '../../src/loaders/raml/Loader'
-import PostmanV2Loader from '../../src/loaders/postman/v2.0/Loader'
+import PostmanCollectionV2Loader from '../../src/loaders/postman/v2.0/Loader'
 
 import SwaggerV2Parser from '../../src/parsers/swagger/v2.0/Parser'
 import RAMLV1Parser from '../../src/parsers/raml/v1.0/Parser'
-import PostmanV2Parser from '../../src/loaders/postman/v2.0/Parser'
+import PostmanCollectionV2Parser from '../../src/parsers/postman/v2.0/Parser'
 
 import SwaggerV2Serializer from '../../src/serializers/swagger/v2.0/Serializer'
 import RAMLV1Serializer from '../../src/serializers/raml/v1.0/Serializer'
-import PostmanV2Serializer from '../../src/serializers/postman/v2.0/Serializer'
+import PostmanCollectionV2Serializer from '../../src/serializers/postman/v2.0/Serializer'
 import InternalSerializer from '../../src/serializers/internal/Serializer'
 
 export const loaders = [
   SwaggerLoader,
   RAMLLoader,
-  PostmanV2Loader
+  PostmanCollectionV2Loader
 ]
 
 export const parsers = [
   SwaggerV2Parser,
   RAMLV1Parser,
-  PostmanV2Parser
+  PostmanCollectionV2Parser
 ]
 
 export const serializers = [
   SwaggerV2Serializer,
   RAMLV1Serializer,
   InternalSerializer,
-  PostmanV2Serializer
+  PostmanCollectionV2Serializer
 ]
 
 export const environment = Environment

configs/web/api-flow-config.js

@@ -2,21 +2,21 @@ import Environment from '../../src/environments/web/Environment'
 
 import SwaggerLoader from '../../src/loaders/swagger/Loader'
 import RAMLLoader from '../../src/loaders/raml/Loader'
-import PostmanV2Loader from '../../src/loaders/postman/v2.0/Loader'
+import PostmanCollectionV2Loader from '../../src/loaders/postman/v2.0/Loader'
 
 import SwaggerV2Parser from '../../src/parsers/swagger/v2.0/Parser'
 import RAMLV1Parser from '../../src/parsers/raml/v1.0/Parser'
-import PostmanV2Parser from '../../src/loaders/postman/v2.0/Parser'
+import PostmanCollectionV2Parser from '../../src/parsers/postman/v2.0/Parser'
 
 import SwaggerV2Serializer from '../../src/serializers/swagger/v2.0/Serializer'
 import RAMLV1Serializer from '../../src/serializers/raml/v1.0/Serializer'
-import PostmanV2Serializer from '../../src/serializers/postman/v2.0/Serializer'
+import PostmanCollectionV2Serializer from '../../src/serializers/postman/v2.0/Serializer'
 import InternalSerializer from '../../src/serializers/internal/Serializer'
 
 export const loaders = [
   SwaggerLoader,
   RAMLLoader,
-  PostmanV2Loader
+  PostmanCollectionV2Loader
 ]
 
 export const parsers = [
@@ -29,7 +29,7 @@ export const serializers = [
   SwaggerV2Serializer,
   RAMLV1Serializer,
   InternalSerializer,
-  PostmanV2Serializer
+  PostmanCollectionV2Serializer
 ]
 
 export const environment = Environment

configs/webworker/api-flow-config.js

@@ -2,34 +2,34 @@ import Environment from '../../src/environments/web/Environment'
 
 import SwaggerLoader from '../../src/loaders/swagger/Loader'
 import RAMLLoader from '../../src/loaders/raml/Loader'
-import PostmanV2Loader from '../../src/loaders/postman/v2.0/Loader'
+import PostmanCollectionV2Loader from '../../src/loaders/postman/v2.0/Loader'
 
 import SwaggerV2Parser from '../../src/parsers/swagger/v2.0/Parser'
 import RAMLV1Parser from '../../src/parsers/raml/v1.0/Parser'
-import PostmanV2Parser from '../../src/loaders/postman/v2.0/Parser'
+import PostmanCollectionV2Parser from '../../src/parsers/postman/v2.0/Parser'
 
 import SwaggerV2Serializer from '../../src/serializers/swagger/v2.0/Serializer'
 import RAMLV1Serializer from '../../src/serializers/raml/v1.0/Serializer'
-import PostmanV2Serializer from '../../src/serializers/postman/v2.0/Serializer'
+import PostmanCollectionV2Serializer from '../../src/serializers/postman/v2.0/Serializer'
 import InternalSerializer from '../../src/serializers/internal/Serializer'
 
 export const loaders = [
   SwaggerLoader,
   RAMLLoader,
-  PostmanV2Loader
+  PostmanCollectionV2Loader
 ]
 
 export const parsers = [
   SwaggerV2Parser,
   RAMLV1Parser,
-  PostmanV2Parser
+  PostmanCollectionV2Parser
 ]
 
 export const serializers = [
   SwaggerV2Serializer,
   RAMLV1Serializer,
   InternalSerializer,
-  PostmanV2Serializer
+  PostmanCollectionV2Serializer
 ]
 
 export const environment = Environment

configs/webworker/webpack.config.babel.js

@@ -4,7 +4,7 @@ const config = {
   target: 'webworker',
   entry: path.resolve(__dirname, './api-flow.js'),
   output: {
-    path: path.resolve(__dirname, '../../../dist/node/'),
+    path: path.resolve(__dirname, '../../../dist/webworker/'),
     filename: 'api-flow.js',
     libraryTarget: 'umd'
   },

src/api-flow-config.js

@@ -13,7 +13,7 @@ import PostmanCollectionV2Parser from './parsers/postman/v2.0/Parser'
 import SwaggerV2Serializer from './serializers/swagger/v2.0/Serializer'
 import RAMLV1Serializer from './serializers/raml/v1.0/Serializer'
 import InternalSerializer from './serializers/internal/Serializer'
-import PostmanV2Serializer from './serializers/postman/v2.0/Serializer'
+import PostmanCollectionV2Serializer from './serializers/postman/v2.0/Serializer'
 import ApiBlueprint1ASerializer from './serializers/api-blueprint/1A/Serializer'
 
 export const loaders = [
@@ -34,7 +34,7 @@ export const serializers = [
   SwaggerV2Serializer,
   RAMLV1Serializer,
   InternalSerializer,
-  PostmanV2Serializer,
+  PostmanCollectionV2Serializer,
   ApiBlueprint1ASerializer
 ]
 

src/loaders/postman/v2.0/Loader.js

@@ -270,17 +270,27 @@ methods.normalizeRequestURL = (item) => {
     return item
   }
 
-  if (typeof item.request.url === 'string') {
-    item.request.urlString = item.request.url
-    item.request.url = methods.createPostmanURLObjectFromURLString(item.request.urlString)
-  }
-  else {
-    if (item.request.url && !item.request.url.domain && item.request.url.host) {
-      item.request.url.domain = item.request.url.host
+  let { url, urlString } = item.request
+
+  if (typeof url === 'object') {
+    // Lets just use this raw string, its gonna have everything
+    if (url.raw) {
+      item.request.urlString = url.raw
+      item.request.url = methods.createPostmanURLObjectFromURLString(url.raw)
+      return item
+    }
+    // cater to some random bug before we do the object normalization
+    if (!url.domain && url.host) {
+      item.request.url.domain = url.host
     }
     item.request.urlString = methods.createPostmanURLStringFromURLObject(item.request.url)
+    return item
   }
 
+  // It's not an object, hope its a string or numeric that'll act like a string
+  item.request.urlString = url
+  item.request.url = methods.createPostmanURLObjectFromURLString(url)
+
   return item
 }
 

src/loaders/postman/v2.0/__tests__/Loader.spec.js

@@ -436,12 +436,14 @@ describe('loaders/postman/v2.0/Loader.js', () => {
       const inputs = [
         { request: { url: '123' } },
         { request: { url: 234 } },
-        { request: { url: { host: 345 } } }
+        { request: { url: { raw: 345 } } },
+        { request: { url: { host: 456 } } }
       ]
       const expected = [
         { request: { url: '123123', urlString: '123' } },
-        { request: { url: 234, urlString: 234 / 2 } },
-        { request: { url: { host: 345, domain: 345 }, urlString: 345 / 2 } }
+        { request: { url: 234 * 2, urlString: 234 } },
+        { request: { url: 345 * 2, urlString: 345 } },
+        { request: { url: { host: 456, domain: 456 }, urlString: 456 / 2 } }
       ]
       const actual = inputs.map(input => __internals__.normalizeRequestURL(input))
       expect(actual).toEqual(expected)

src/parsers/swagger/v2.0/Parser.js

@@ -1252,6 +1252,12 @@ methods.convertParameterObjectIntoParameter = (parameterEntry) => {
     applicableContexts
   }
 
+  if (typeof parameter.example !== 'undefined') {
+    paramInstance.examples = List([parameter.example])
+  } else if (typeof parameter['x-example'] !== 'undefined') {
+    paramInstance.examples = List([parameter['x-example']])
+  }
+
   if (parameter.type === 'array' && parameter.items) {
     const { value } = methods.convertParameterObjectIntoParameter({
       key: null,