Release 1.4.4 (apideck-libraries#102)

CHANGELOG.md

@@ -1,3 +1,11 @@
+## v1.4.4 - (2021-07-22)
+
+### Enhancement
+
+- Updated docs with an example for filtering
+- Bumped openapi-format to 1.2.5
+- Fix to prevent the unwanted addition 'Variation Tests'
+
 ## v1.4.3 - (2021-07-22)
 
 ### Bugfix

README.md

@@ -46,6 +46,7 @@ OR
 4. Start converting your OpenAPI document to Postman
 
 All configuration options to convert from OpenAPI to Postman can be found in the [openapi-to-postman](https://github.com/postmanlabs/openapi-to-postman/blob/develop/OPTIONS.md) package documentation.
+All configuration options to filter flags/tags/methods/operations/... from OpenAPI can be found in the [openapi-format](https://github.com/thim81/openapi-format#openapi-filter-options) package documentation.
 
 ## Installation
 
@@ -92,6 +93,7 @@ Options:
   -l, --local                Use local OAS to port to Postman collection                      [string]
   -b, --baseUrl              Override spec baseUrl to use in Postman                          [string]
   -o, --output               Write the Postman collection to an output file                   [string]
+  --oaOutput                 Write the (filtered) OpenAPI file to an output file              [string]
   -n, --runNewman            Run Newman on newly created collection                           [boolean]
   --newmanRunOptions         JSON stringified object to pass options for configuring Newman   [string]
   -d, --newmanIterationData  Iteration data to run Newman with newly created collection       [string]
@@ -101,7 +103,7 @@ Options:
   -t, --includeTests         Inject Portman test suite (default: true)                        [boolean]
   -c, --portmanConfigFile    Path to Portman settings config file (portman-config.json)       [string]
   -s, --postmanConfigFile    Path to openapi-to-postman config file (postman-config.json)     [string]
-  -s, --filterFile           Path to openapi-format config file (oas-format-filter.json)      [string]
+  --filterFile               Path to openapi-format config file (oas-format-filter.json)      [string]
   --envFile                  Path to the .env file to inject environment variables            [string]
   --cliOptionsFile           Path to Portman CLI options file                                 [string]
   --init                     Configure Portman CLI options in an interactive manner           [string]
@@ -167,6 +169,14 @@ portman -l ./tmp/specs/crm.yml -o ./tmp/specs/crm.Postman.json
 portman -l ./tmp/specs/crm.yml -t false
 ```
 
+- Filter OpenAPI and generate collection.
+
+```
+portman -u https://specs.apideck.com/crm.yml --filterFile examples/cli-filtering/oas-format-filter.json
+```
+
+For more details, review the [cli-filtering example](https://github.com/apideck-libraries/portman/tree/main/examples/cli-filtering).
+
 - Upload newly generated collection to Postman, which will upsert the collection, based on the collection name
 
 ```

examples/cli-filtering/oas-format-filter.json

@@ -0,0 +1,8 @@
+{
+  "methods": [],
+  "tags": ["Companies","Opportunities","Contacts", "Pipelines", "Notes", "Users", "Activities"],
+  "operationIds": [],
+  "operations": [],
+  "flags": [],
+  "flagValues": []
+}

examples/cli-filtering/portman-cli-options.json

@@ -0,0 +1,10 @@
+{
+  "url": "https://specs.apideck.com/crm.yml",
+  "baseUrl": "http://localhost:3050",
+  "output": "./examples/cli-filtering/crm.postman.json",
+  "oaOutput": "./examples/cli-filtering/filtered-crm.leads.yml",
+  "filterFile": "./examples/cli-filtering/oas-format-filter.json",
+  "includeTests": true,
+  "syncPostman": false,
+  "runNewman": false
+}

examples/cli-filtering/readme.md

@@ -0,0 +1,120 @@
+# Portman CLI options
+
+This example contains a setup that focuses on the filtering of the OpenAPI document before it gets converted by Portman, into a Postman collection.
+
+_use-case_: Reduce a large OpenAPI document, by filtering out operations based on flags, tags, methods, operations, ... for which you want to generate Postman tests.
+
+## CLI usage
+
+```ssh
+portman --cliOptionsFile ./examples/cli-filtering/portman-cli-options.json
+```
+
+## Portman CLI options settings
+
+./examples/cli-filtering/portman-cli-options.json >>
+
+```json
+{
+  "url": "https://raw.githubusercontent.com/apideck-libraries/openapi-specs/master/crm.yml",
+  "baseUrl": "http://localhost:3050",
+  "output": "./examples/cli-filtering/crm.postman.json",
+  "oaOutput": "./examples/cli-filtering/filtered-crm.leads.yml",
+  "filterFile": "./examples/cli-filtering/oas-format-filter.json",
+  "includeTests": true,
+  "syncPostman": false,
+  "runNewman": false
+}
+```
+
+## Example explained
+
+The used [remote spec](https://raw.githubusercontent.com/apideck-libraries/openapi-specs/master/crm.yml) contains a wide range of API operations for Companies, Opportunities, ... but for our test suite, we want to focus on just generation tests for the "Leads" API operations.
+
+To do this, we can use the `filterFile` option from Portman to filter out all the unwanted API operations based on the tags used in the OpenAPI spec, to only keep the "Leads" `tags`.
+
+In the Portman CLI config above, we have defined the parameter `"filterFile":  "./examples/cli-filtering/oas-format-filter.json"`, which contains the items to filter out.
+
+The OpenAPI spec has tagged its operations with the appropriate tags, so it is very straightforward to use the "tags" as target for filtering.
+
+List of tags that used in the OpenAPI spec:
+```yaml
+"tags": [
+    {
+      "name": "Companies",
+      "description": ""
+    },
+    {
+      "name": "Opportunities",
+      "description": ""
+    },
+    {
+      "name": "Leads",
+      "description": ""
+    },
+    {
+      "name": "Contacts",
+      "description": ""
+    },
+    {
+      "name": "Pipelines",
+      "description": ""
+    },
+    {
+      "name": "Notes",
+      "description": ""
+    },
+    {
+      "name": "Users",
+      "description": ""
+    },
+    {
+      "name": "Activities",
+      "description": ""
+    }
+  ]
+```
+
+The filtering mechanism build in Portman, leverages the [openapi-format](https://github.com/thim81/openapi-format#openapi-filter-options) package.
+The "openapi-format" package offers a wide range of configuration options to filter flags/tags/methods/operations/... from the OpenAPI document.
+
+| Type         | Description                   | Type  | Examples                             |
+|--------------|-------------------------------|-------|--------------------------------------|
+| methods      | a list OpenAPI methods.       | array | ['get','post','put']                 |
+| tags         | a list OpenAPI tags.          | array | ['Activities','Users']               |
+| operationIds | a list OpenAPI operation ID's.| array | ['leadsAll','leadsAdd']              |
+| operations   | a list OpenAPI operations.    | array | ['GET::/crm/leads','PUT::/crm/leads']|
+| flags        | a list of custom flags        | array | ['x-exclude','x-internal']           |
+
+By specifying the desired filter values for the available filter types, Portman will use the openapi-format CLI to strip out any
+matching item from the OpenAPI document. You can combine multiple types to filter out a range of OpenAPI items.
+
+In our example case, we can just use the "tags" option to filter out the unwanted API operations.
+
+./examples/cli-filtering/oas-format-filter.json >>
+
+```json
+{
+  "methods": [],
+  "tags": ["Companies","Opportunities","Contacts", "Pipelines", "Notes", "Users", "Activities"],
+  "operationIds": [],
+  "operations": [],
+  "flags": [],
+  "flagValues": []
+}
+```
+
+Resulting in 2 outputs:
+
+1. [Postman collection output](crm.postman.json): The generated Postman collection with only the "Leads" API requests, based on the filtered OpenAPI document
+2. [OpenAPI output](filtered-crm.leads.yml): Since we defined the `oaOutput` parameter, the filtered OpenAPI output will be saved in the defined file path "filtered-crm.leads.yml". 
+
+The `oaOutput` parameter is completely optional. It can be handy if you want to review/download/share the filtered OpenAPI document.
+
+Results without filtering:
+
+![](./images/postman-unfiltered.png)
+
+Filtered results:
+
+![](./images/postman-filtered.png)

package.json

@@ -73,7 +73,7 @@
     "fs-extra": "^10.0.0",
     "newman": "^5.2.4",
     "node-emoji": "^1.10.0",
-    "openapi-format": "^1.2.4",
+    "openapi-format": "^1.2.5",
     "openapi-to-postmanv2": "^2.8.0",
     "openapi-types": "^9.0.3",
     "ora": "^5.4.1",

src/Portman.ts

@@ -95,19 +95,23 @@ export class Portman {
         portmanConfigFile,
         portmanConfigPath,
         postmanConfigFile,
+        filterFile,
+        oaOutput,
         envFile,
         includeTests,
         runNewman,
         newmanIterationData,
         syncPostman
       }
     } = this
+
     // --- Portman - Show processing output
     console.log(chalk.red(consoleLine))
 
     oaUrl && console.log(chalk`{cyan  Remote Url: } \t\t{green ${oaUrl}}`)
     oaLocal && console.log(chalk`{cyan  Local Path: } \t\t{green ${oaLocal}}`)
     output && console.log(chalk`{cyan  Output Path: } \t\t{green ${output}}`)
+    oaOutput && console.log(chalk`{cyan  OpenAPI Output Path: } \t{green ${oaOutput}}`)
 
     cliOptionsFile && console.log(chalk`{cyan  Portman CLI Config: } \t{green ${cliOptionsFile}}`)
     console.log(
@@ -121,6 +125,8 @@ export class Portman {
       }}`
     )
 
+    filterFile && console.log(chalk`{cyan  Filter Config: } \t{green ${filterFile}}`)
+
     console.log(chalk`{cyan  Environment: } \t\t{green ${envFile}}`)
     console.log(chalk`{cyan  Inject Tests: } \t{green ${includeTests}}`)
     console.log(chalk`{cyan  Run Newman: } \t\t{green ${!!runNewman}}`)
@@ -164,7 +170,7 @@ export class Portman {
 
   async parseOpenApiSpec(): Promise<void> {
     // --- OpenApi - Get OpenApi file locally or remote
-    const { oaLocal, oaUrl, filterFile } = this.options
+    const { oaLocal, oaUrl, filterFile, oaOutput } = this.options
 
     let openApiSpec = oaUrl && (await new DownloadService().get(oaUrl))
 
@@ -190,7 +196,7 @@ export class Portman {
     }
 
     if (filterFile && (await fs.pathExists(filterFile))) {
-      const openApiSpecPath = './tmp/converted/filtered.yml'
+      const openApiSpecPath = oaOutput ? oaOutput : './tmp/converted/filtered.yml'
 
       await execShellCommand(
         `npx openapi-format ${openApiSpec} -o ${openApiSpecPath} --yaml --filterFile ${filterFile}`
@@ -290,7 +296,12 @@ export class Portman {
       testSuite
     } = this
 
-    if (includeTests && testSuite) {
+    if (
+      includeTests &&
+      testSuite &&
+      testSuite?.variationTests?.length &&
+      testSuite?.variationTests?.length > 0
+    ) {
       // Inject variations
       this.variationWriter = new VariationWriter({
         testSuite: testSuite,

src/index.ts

@@ -85,6 +85,10 @@ require('dotenv').config()
       describe: 'Path to openapi-format config file (oas-format-filter.json)',
       type: 'string'
     })
+    .option('oaOutput', {
+      describe: 'Write the (filtered) OpenAPI file to an output file',
+      type: 'string'
+    })
     .option('envFile', {
       describe: 'Path to the .env file to inject environment variables',
       type: 'string'
@@ -161,6 +165,7 @@ require('dotenv').config()
     options?.postmanConfigFile || __dirname + '/../postman-config.default.json'
   const envFile = options?.envFile || '.env'
   const filterFile = options.filterFile
+  const oaOutput = options.oaOutput || ''
 
   const portman = new Portman({
     ...options,
@@ -176,14 +181,15 @@ require('dotenv').config()
     postmanConfigFile,
     postmanConfigPath,
     envFile,
-    filterFile
+    filterFile,
+    oaOutput
   })
 
   if (options.uploadOnly) {
     // Upload only, skip all the rest
-    portman.uploadOnly()
+    await portman.uploadOnly()
   } else {
     // Run full portman conversion
-    portman.run()
+    await portman.run()
   }
 })()

src/types/PortmanOptions.ts

@@ -18,6 +18,7 @@ export interface PortmanOptions {
   postmanConfigFile?: string
   postmanConfigPath?: string
   filterFile?: string
+  oaOutput?: string
   envFile?: string
   cliOptionsFile?: string
   oaLocal?: string