https://github.com/kielabokkie/blueman
Convert a generated API Blueprint JSON file into a Postman collection
https://github.com/kielabokkie/blueman
api-blueprint postman
Last synced: 7 months ago
JSON representation
Convert a generated API Blueprint JSON file into a Postman collection
- Host: GitHub
- URL: https://github.com/kielabokkie/blueman
- Owner: kielabokkie
- License: mit
- Created: 2014-05-22T23:35:40.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2017-05-30T20:40:20.000Z (over 8 years ago)
- Last Synced: 2025-03-24T08:23:18.524Z (7 months ago)
- Topics: api-blueprint, postman
- Language: PHP
- Size: 69.3 KB
- Stars: 149
- Watchers: 15
- Forks: 19
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Blueman
[](https://twitter.com/kielabokkie)
[](https://travis-ci.org/pixelfusion/blueman)
[](https://codecov.io/github/pixelfusion/blueman)
[](https://www.codacy.com/public/pixelfusion/blueman)
[](https://packagist.org/packages/pixelfusion/blueman)
[](LICENSE.md)
[](https://gitter.im/pixelfusion/blueman)
Convert an [API Blueprint](http://apiblueprint.org) JSON file into a [Postman](http://www.getpostman.com) collection.
## Install Blueman as a Phar (recommended)
Use the installer to download Blueman:
```sh
$ 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:
```sh
$ 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:
```sh
$ blueman self-update
```
## Install using Composer
Blueman can also be installed using Composer if you prefer that:
```sh
$ 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](https://github.com/apiaryio/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:
```sh
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](https://github.com/refractproject/refract-spec/blob/master/namespaces/api-description-namespace.md). 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:
```sh
$ 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.:
```sh
$ ./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:
```sh
$ 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:
```sh
$ 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:
```sh
$ 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:
```sh
$ 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](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
```sh
$ blueman convert api.json --include-tests
```
If the name of your test file is not `blueman.tests.md` then specify the filename:
```sh
$ blueman convert api.json --include-tests --tests-filename=.md
```