romulogm / blueman

Convert a generated API Blueprint JSON file into a Postman collection

Blueman

Convert an API Blueprint JSON file into a Postman collection.

Install Blueman as a Phar (recommended)

Use the installer to download Blueman:

$ curl -sS http://blueman.pixelfusion.co.nz/installer.php | php

This will grab the latest version of Blueman and copy it to your current directory. We recommend moving it to the bin directory so you can run the Blueman from anywhere:

$ mv blueman.phar /usr/local/bin/blueman

Whenever there is a new version of Blueman you can run self-update to update to the latest version:

$ blueman self-update

Install using Composer

Blueman can also be installed using Composer if you prefer that:

$ composer create-project pixelfusion/blueman your-project-name

Prerequisites

The API Blueprint JSON file that you want to convert with Blueman should be created using Drafter. By default Drafter creates refract formatted JSON files but Blueman only supports the AST format. You will have to force Drafter to use AST by passing the -t parameter, for example:

drafter -f json -t ast -o api.json api.md

Note: As of December 2015 the API Blueprint AST format has been deprecated. The API Blueprint AST has been superseded by API Description Refract Namespace. At this point Blueman only supports the AST format so as soon as Drafter drops support for generating AST formatted files, Blueman won't work anymore. Pull Requests to add support for the refract format are highly appreciated!

Usage

To generate a Postman collection you run the convert command. For example, if the API Blueprint JSON file you generated is called api.json you would execute the following command:

$ blueman convert api.json

Note: If you installed Blueman using Composer you have to replace blueman with ./bin/console in all the example commands, e.g.:

$ ./bin/console convert api.json

This command will generate a file called collection.json, which you can import in Postman.

By default Blueman will look for the JSON file in the same location as where you are running the command. If your file is in another directory, you need to specify the path:

$ blueman convert api.json --path=/Users/wouter/Desktop

Specify output file

By default Blueman will create a collection.json file in the current directory. You can save the file to a different folder and change the output filename by passing the output parameter:

$ blueman convert api.json --output=/Users/wouter/Desktop/postman_collection.json

Setting the host

The base host of your API can be set in a couple of different ways.

First of all you can specify it in your API Blueprint as metadata by adding the following line to the top of your API Blueprint Markdown file:

HOST: https://api.example.com/v1

If your Markdown file doesn't have the host metadata or if you want to overwrite it, you can specify the host when executing the convert command:

$ blueman convert api.json --host=https://api.example.com/v1

Lastly, if you don't do either of the above you'll be prompted to set the host when you execute the convert command.

TIP: If you use environments in Postman to test your API on different servers (sandbox, user acceptance testing, etc.) you can use the host option to specify your placeholder keys that you've setup in Postman's environment config:

$ blueman convert api.json --host=https://api.{{host}}/v1

Postman tests

Blueman also allows you to define Postman tests.

To use this feature you have to create a Markdown file in your path where api.json is located (see --path option). By default, Blueman will try to read a file called blueman.tests.md. Check the test/api.test.md file for an example of the syntax. You can use a different name if you like but you will need to specify the --test-filename parameter when you run the convert command.

Usage example

$ blueman convert api.json --include-tests 

If the name of your test file is not blueman.tests.md then specify the filename:

$ blueman convert api.json --include-tests --tests-filename=<YOUR_FILNAME>.md