❯ Installation

Use the package manager npm which is bundled with node to install ufonaut.

npm install -g @b-pagis/ufonaut

❯ Usage

:scroll: NOTICE: By default this utility, when converting, replaces request body, header and query parameters' values with interpolated parameter names. As an example "keyName":"<string>" will be replaced with "keyName":"{{keyName}}". This gives flexibility and ability to contain all information in variables.

Run interactive mode

ufonaut

or

ufonaut cli

Convert Open API documentation to postman collection

ufonaut convert -i [file-location] -o [output-file-location]

Other options

| Short flag | Long name | Required | Description | | ---------- | ---------------------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------ | | -i | --input | yes | Local path or remote URL to open api JSON file. | | -o | --output | yes | File path where postman collection will be saved. | | -d | --order | | Path to order config JSON file. | | -s | --scripts | | Path to scripts catalog containing test and pre-request catalogs with corresponding script files. | | -u | --username | | In case open api file is accessed by URL that is protected with basic auth, this option is used to provide basic auth username. | | -p | --password | | In case open api file is accessed by URL that is protected with basic auth, this option is used to provide basic auth password. | | -x | --x-api-key | | In case open api file is accessed by URL that is protected with X-API-KEY header, this option is used to provide X-API-KEY header value. | | -b | --bearer-token | | In case open api file is accessed by URL that is protected with Bearer token, this option is used to provide Authorization: Bearer header value. | | -cr | --rename | | Postman collection's name. | | -ca | --collection-auth-type | | Postman Collection's auth type [basic, apikey, bearer]. Will only affect those endpoints that are using some kinds of authentication option. | | -cu | --collection-basic-auth-username | | Postman Collection's basic auth username. | | -cp | --collection-basic-auth-password | | Postman Collection's basic auth password. | | -ck | --collection-api-key-auth-key | | Postman Collection's api key auth key (default: "X-API-KEY"). | | -cv | --collection-api-key-auth-value | | Postman Collection's api key auth key value. | | -cl | --collection-api-key-auth-location | | Postman Collection's api key auth location [header, query] (default: "header"). | | -cb | --collection-bearer-auth-token | | Postman Collection's bearer auth token value. | | -cf | --collection-forced-auth | | Force to use specified auth type for all endpoints (default: false). | | -t | --script-template | | Path to scripts template catalog. |

Create a set

ufonaut create-sets -i [file-location] -o [output-file-location] -c [sets-config-location]

Other options

| Short flag | Long name | Required | Description | | ---------- | -------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------ | | -i | --input | yes | Local path or remote URL to open api JSON file. | | -c | --sets-config | yes | Path to sets config JSON file. | | -o | --output | yes | Path where to output sets collections. | | -u | --username | | In case open api file is accessed by URL that is protected with basic auth, this option is used to provide basic auth username. | | -p | --password | | In case open api file is accessed by URL that is protected with basic auth, this option is used to provide basic auth password. | | -x | --x-api-key | | In case open api file is accessed by URL that is protected with X-API-KEY header, this option is used to provide X-API-KEY header value. | | -b | --bearer-token | | In case open api file is accessed by URL that is protected with Bearer token, this option is used to provide Authorization: Bearer header value. |

List endpoints in open api documentation

ufonaut endpoints -i [file-location]

Other options

| Short flag | Long name | Required | Description | | ---------- | -------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------ | | -i | --input | yes | Local path or remote URL to open api JSON file. | | -n | --normalized | | In addition, outputs normalized endpoint path that could be used for script files. | | -t | --output-type | | Output file type [md, csv]. By default prints to console. | | -o | --output | | Output file location. | | -u | --username | | In case open api file is accessed by URL that is protected with basic auth, this option is used to provide basic auth username. | | -p | --password | | In case open api file is accessed by URL that is protected with basic auth, this option is used to provide basic auth password. | | -x | --x-api-key | | In case open api file is accessed by URL that is protected with X-API-KEY header, this option is used to provide X-API-KEY header value. | | -b | --bearer-token | | In case open api file is accessed by URL that is protected with Bearer token, this option is used to provide Authorization: Bearer header value. |

Ordering

Option that allows ordering endpoints in the specified way. This option will provide postman collection with flat structure. Not specified endpoints are included into the list after ordered ones.

Config file example

{
  "order": [
    {
      "method": "post",
      "path": "user"
    },
    {
      "method": "post",
      "path": "store/order"
    },
    {
      "method": "get",
      "path": "pet/findByStatus"
    }
  ]
}

Sets

Option that allows to create small postman collections for dedicated scenarios.

Config options

| Key | Type | Required | Description | | ------------------------------------------ | ------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sets | array | yes | Array of sets configs. | | sets[].collectionName | string | yes | Name for the set. Value will be used for both - postman collection name and exported file name. | | sets[].scriptsPath | string | | Path to scripts catalog containing test and pre-request catalogs with script files. | | sets[].template.preRequestTemplateFilePath | string | | Path to pre-request template catalog. | | sets[].auth | object | | Authentication settings for endpoints in the collection. | | sets[].auth.type | enum | | Postman Collection's auth type [basic, apikey, bearer]. | | sets[].auth.forced | boolean | | Force to use specified auth type for all endpoints. | | sets[].auth.basic | object | | Configuration for basic authentication type. Cannot be used with apikey or bearer. | | sets[].auth.basic.username | string | | Postman Collection's basic auth username. | | sets[].auth.basic.password | string | | Postman Collection's basic auth password. | | sets[].auth.apikey | object | | Configuration for api key authentication type. Cannot be used with basic bearer. | | sets[].auth.apikey.location | enum | | Postman Collection's api key auth location. Possible values - header, query. | | sets[].auth.apikey.key | string | | Postman Collection's api key auth key. | | sets[].auth.apikey.value | string | | Postman Collection's api key auth key value. | | sets[].auth.bearer | object | | Configuration for Bearer token authentication type. Cannot be used with basic, apikey. | | sets[].auth.bearer.token | string | | Postman Collection's bearer auth token value that will be added to Authorization: Bearer header. | | sets[].order | array | yes | List of endpoints for following set. It is the same configuration as order config, with the only exception that endpoints that are not provided in following list will be discarded. |

Config example

{
  "sets": [
    {
      "collectionName": "pc-sets-store-example",
      "scriptsPath": "examples/scripts",
      "template": {
        "preRequestTemplateFilePath": "examples/scripts/template/pre-request.template"
      },
      "auth": {
        "type": "basic",
        "forced": false,
        "basic": {
          "username": "user",
          "password": "user-password"
        }
      },
      "order": [
        {
          "method": "post",
          "path": "store/order"
        },
        {
          "method": "get",
          "path": "store/order/:orderId"
        },
        {
          "method": "get",
          "path": "store/inventory"
        }
      ]
    },
    {
      "collectionName": "pc-sets-pet-example",
      "auth": {
        "type": "apikey",
        "apikey": {
          "location": "header",
          "key": "x-my-key",
          "value": "key-123"
        }
      },
      "order": [
        {
          "method": "get",
          "path": "pet/findByStatus"
        },
        {
          "method": "put",
          "path": "pet"
        },
        {
          "method": "get",
          "path": "pet/findByTags"
        },
        {
          "method": "delete",
          "path": "pet/:petId"
        },
        {
          "method": "post",
          "path": "pet"
        }
      ]
    }
  ]
}

:scroll: NOTICE: Only those endpoints that are specified in set config will be included into set.

Scripts

When storing everything in variables, it becomes possible to have some kind of content manipulation in either pre-request or test tab. This options gives possibility to load pre-request and test scripts from files to endpoints. However this option enforces some path and file name rules.

Path rules

Path must contain two catalogs that are named pre-request and test in it.

File name

Each catalog must contain a .js file with following rules method-path, where:

• method - is HTTP method (e.g. post, get, etc)
• path - is full path to the resource with removed non letter symbols, except dash, from it and placed in lowercase. E.g. for endpoint that is named GET /pet/findByStatus-example - the file name must be get-petfindbystatus-example.js.

Catalog structure example

.
├── scripts
    ├── pre-request
    │   └── get-petfindbystatus-example.js
    └── test
        └── get-petfindbystatus-example.js

Script templates

Postman does not allow direct body manipulation (see #4808). The only way to do it, is to put request body into variable that can be used in pre-request script, but doing it manually is very tedious task. With this option it is possible to automate this task, by creating a template that will be used in every endpoint that has request body.

Template supports following parameters:

• requestBody - will be replaced by actual request body. In the request tab a {{requestBody}} parameter will be placed instead of actual request.
• scriptContent - will be replaced with the content of pre-request script file.

Parameters must be entered between <%%= and =%%>.

Template example

var requestBody = <%%=requestBody=%%>;

<%%=scriptContent=%%>

pm.environment.set('requestBody', JSON.stringify(requestBody));

❯ Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

:scroll: NOTICE: if you are working on Windows, then following scripts will not work

• refresh,
• clean:all,
• clean:lib,
• build,
• start

This is because rm -rf command is used. Please adjust it locally and please avoid committing updated commands. Thank you in advance for your contribution.

❯ License

ISC