pixelfusion / blueman
Generate Postman collections from API Blueprint JSON files
Installs: 700
Dependents: 0
Suggesters: 0
Security: 0
Stars: 149
Watchers: 16
Forks: 18
Open Issues: 5
Requires
- ramsey/uuid: ~2.7
- symfony/config: ~2.8
- symfony/console: ~2.4
- symfony/debug: ~2.8
- symfony/filesystem: ~2.8
- symfony/stopwatch: ~2.8
Requires (Dev)
- phpunit/phpunit: ~3.7
- satooshi/php-coveralls: ~0.6
This package is not auto-updated.
Last update: 2024-11-05 21:06:33 UTC
README
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