Create Postman collections out of tests

We use Spring (Auto) REST Docs to automatically generate API documentation out of tests, but so far we were still creating Postman collections manually. We have build our own extension to Spring REST Docs called Spring Auto REST Docs that helps us to create the documentation out of tests with even less effort. Of course we want to continue in that fashion and automate as much as possible.

A common complaint about Spring REST Docs is that it does not offer an API playground like Swagger, e.g. see #47 and #213 . The Swagger API playground is nice to get a first glimpse of the API and to play around a bit, but it is far away from the flexibility that tools like Postman, Insomnia, or Paw offer. Among other things Postman offers to script API calls together. There are also Swagger to Postman converters out there, e.g. Swagman.

One issue with creating Postman collections out of Spring REST Docs tests is that Spring REST Docs creates separate snippets for each test and only a separate build step combines them afterwards. However, Postman collections are stored in single JSON file. Therefore, such a post processing step is required to create a Postman collection.

Initially, I thought that such a feature has to be integrated into Spring REST Docs itself. But after seeing that both Postman and Insomnia can import cURL commands, I started looking at standalone converters. Sadly, I didn’t find a single maintained cURL to Postman converter. It’s a feature in Postman, but not available as open source. In contrast Insomnia offers insomnia-importers as open source. It was easy to get started with the Insomnia cURL importer and to convert Spring REST Docs cURL snippets to Insomnia collections. Postman collections are not too different from Insomnia collections and thus a converter isn’t too complicated, especially because not all features are required (see Postman Schema). The result is restdocs-to-postman: A npm package that converts Spring REST Docs cURL snippets to Postman or Insomnia collections.

restdocs-to-postman traverses the generated-snippets folder (or any other folder) generated by Spring REST Docs recursively and looks for curl_request.adoc or curl_request.md files. A curl_request.adoc file looks like:

[source,bash]
----
$ curl 'http://localhost:8080/items' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"description":"Hot News"}'
----

Afterwards the cURL command is extracted and put into the Insomnia converter. As an optional next step the host and/or headers are replaced — usually this is done to insert placeholders like {{host}} or {{oauthToken}} . If the target is a Postman collection instead of an Insomnia collection, the last step converts the Insomnia collection to a Postman collection. The resulting JSON files can directly be imported into Postman or Insomnia.

Using restdocs-to-postman as a CLI tool looks as follows and the result is show in the screenshots below:

$ restdocs-to-postman --folder generated-snippets --export-format postman --output postman-collection.json

Replacements can be passed with --replacements replacements.json and an example for a replacement file is shown below:

{
  "host": {
    "before": "http://localhost:8080",
    "after": "{{host}}"
  },
  "headers": [
    {
      "name": "Authorization",
      "newValue": "{{oauth2Token}}"
    }
  ]
}

Result after importing into Postman

Result after importing into Insomnia

An alternative to this approach is to go via RAML. There is a new restdocs-raml project that helps to produce RAML out of Spring REST Docs tests. RAML files can be imported into Postman or Paw and can be used to create an interactive REST console. It is easy to use in an existing Spring REST Docs project by just switching to the restdocs-raml document method that wraps the original one. However, restdocs-raml can not be used with Spring Auto REST Docs yet, because it is based on some of the original Spring REST Docs snippets.