fbenz / restdocs-to-postman

Converts Spring REST Docs cURL snippets to Postman and Insomnia collections

End-of-life Notice

This project is officially end-of-life. Users are welcome to maintain it in a fork, but there will be no more changes published from this source.

---

Spring REST Docs to Postman/Insomnia Converter

This project collects cURL commands generated by Spring REST Docs and converts them to a Postman or Insomnia collection.

Output formats:

• Postman Collection Format v2.1.0
• Insomnia export format v3

Spring REST Docs is an awesome tool to generate documentation out of tests, but no API playground is provided out of the box. Tools like Postman or Insomnia offer lots of features to play with APIs and this project helps to bootstrap Postman and Insomnia collections from Spring REST Docs cURL snippets. Such a feature has been requested by several people, for example in Spring REST Docs issue 47.

This project can also be used with Spring Auto REST Docs because the very same cURL snippets are generated.

Installation

For usage on command line, install globally

npm install -g restdocs-to-postman

For programmatic usage, install in project

npm install --save restdocs-to-postman

Command Line Usage

restdocs-to-postman --input generated-snippets --export-format postman --determine-folder secondLastFolder --output postman-collection.json

From the given folder, all folders are recursively scanned for curl-request.adoc and curl-request.md files. Requests can be sorted into folders with --determine-folder secondLastFolder. The function secondLastFolder is the only one for now and puts a request from ../items/get/curl-request.adoc into a folder called item. Host and header replacements can be used with --replacements replacements.json. See replacement-example.json for an example of a replacement file.

Programmatic Usage

const converter = require('restdocs-to-postman');

// Convert Spring REST Docs cURL commands to Postman/Insomnia collections
const folderToScan = './target/generated-snippets';
const exportFormat = 'postman';
const replacements = {
  host: {
    before: 'http://localhost:8080',
    after: '{{host}}'
  },
  headers: [
    {
      name: 'Authorization',
      newValue: '{{oauth2Token}}'
     }
  ]
};
const output = converter.convert({folderToScan, exportFormat, replacements});

// Print the result
console.log(output);

Running Tests

Run all tests

npm test

Contributing

• Submit a Pull Request for any enhancement you made.
• Create an issue describing your particular problem.

License

restdocs-to-postman is Open Source software released under the Apache 2.0 license.

restdocs-to-postman's Issues

Keep folder structure in Postman?

Thank you very much for this project! :)

I'm wondering if it would be possible to keep the folder structure that I have for my generated snippets in Postman?

For example, I have these generated snippets:

But after using restdocs-to-postman and opening the collection in Postman I see this:

i.e. all the requests are in the same folder.

unable to convert adoc to postman collection

Hi @fbenz
I am unable to convert my adoc to postman collection.
Please find below the error message , I have also attached the adoc file as well , could you please help me on this ,

Appreciate your support!

D:>restdocs-to-postman --input adoc --export-format postman --determine-folder secondLastFolder --output postman-collection.json
C:\Users\Akaram\AppData\Roaming\npm\node_modules\restdocs-to-postman\src\insomnia3-to-postman21.js:86
path: parsedUrl.pathname.split('/'),
^

TypeError: Cannot read property 'split' of null
at toPostmanItem (C:\Users\Akaram\AppData\Roaming\npm\node_modules\←[4mrestdocs-to-postman←[24m\src\insomnia3-to-postman21.js:86:42)
at C:\Users\Akaram\AppData\Roaming\npm\node_modules\←[4mrestdocs-to-postman←[24m\src\insomnia3-to-postman21.js:174:36
at Array.forEach ()
at Object.module.exports.toPostmanCollection (C:\Users\Akaram\AppData\Roaming\npm\node_modules\←[4mrestdocs-to-postman←[24m\src\insomnia3-to-postman21.js:170:10)
at Object.module.exports.convert (C:\Users\Akaram\AppData\Roaming\npm\node_modules\←[4mrestdocs-to-postman←[24m\src\convert.js:86:53)
at Object.module.exports.go (C:\Users\Akaram\AppData\Roaming\npm\node_modules\←[4mrestdocs-to-postman←[24m\src\cli.js:45:30)
at Object. (C:\Users\Akaram [curl-request.txt](https://github.com/fbenz/restdocs-to-postman/files/8021590/curl-request.txt) \AppData\Roaming\npm\node_modules\←[4mrestdocs-to-postman←[24m\bin\cli:3:23)
←[90m at Module._compile (internal/modules/cjs/loader.js:1085:14)←[39m
←[90m at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)←[39m
←[90m at Module.load (internal/modules/cjs/loader.js:950:32)←[39m

CLI: Default export format does not work

The export format parameter should have postman has a default value and it's documented like this:

-e, --export-format [format]  export format (default: postman)

So the following command

restdocs-to-postman --folder generated-snippets --output postman-collection.json

should produce the same result as

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

but it produces an empty JSON file.

Improve tests

1. Compare actual JSON output and expected JSON fixture with a JSON matcher instead of a string matcher to get better error messages and to be more flexible on the format of the fixtures.
2. Store pretty printed JSON in the fixture files to increase readability and to get better diffs if parts are changed.

Support for nested folder determine-folder option

#17

Our project has a number of endpoints which are nested by their endpoint name grouping. The secondLastFolder option flattens this out, and the name chosen is not descriptive enough to show its original position in our API.

Therefore a new CLI folder option to maintain the folder and sub-folder structure of our endpoints would be very useful.

AC:
Pass in --determine-folder nestedFolders in the CLI.
Using the example test data in this project with one extra level, the output in Insomnia/Postman would look like:

Support urlencoded and formdata bodies when converting to Postman

This is already supported for Insomnia, because the cURL to Insomnia converter provided by Insomnia is used. However, only Insomnia bodies with a text field (e.g. JSON bodies) are converted correctly to Postman.

Urlencoded

Insomnia

  "body": {
    "mimeType": "application\/x-www-form-urlencoded",
    "params": [
      {
        "name": "command",
        "value": "increase"
      }
    ]
  }

This can be detected comparing mimeType to application/x-www-form-urlencoded.
Postman

  "body": {
    "mode": "urlencoded",
    "urlencoded": [
      {
        "key": "command",
        "value": "increase"
      }
    ]
  }

Formdata

Insomnia

  "body": {
    "mimeType": "multipart\/form-data",
    "params": [
      {
        "name": "command",
        "value": "increase"
      }
    ]
  }

This can be detected by checking whether params is there and the mimeType is not application/x-www-form-urlencoded.
Postman

  "body": {
    "mode": "formdata",
    "formdata": [
      {
        "key": "command",
        "value": "increase"
      }
    ]
  }

References:

• cURL to Insomnia: https://github.com/getinsomnia/insomnia/blob/develop/packages/insomnia-importers/src/importers/curl.js#L167
• Postman collection schema: https://schema.getpostman.com/json/collection/v2.1.0/docs/index.html

Add the ability to replace parts of URL paths with replacements.json

Often in RESTful urls, there are IDs of objects used as a part of the path. This can be seen even in the current test data:

"name": "items/1"

This is a common occurrence as the output of the Spring RESTdocs tests will use the values that were created in testing. It is highly likely that these values are invalid in the development/integration environments running these services. Instead, allowing a variable replacement for these values is useful.

The replacement.json framework is already set up to handle this problem for headers and host name. This feature will extend that functionality to allow parameterization of the path parts.

AC:
Support "pathReplacements" in the replacements.json. This will search for a part in the URL matching the "part" object. The next part of the path (after a "/" character) will be replaced by the newValue if the oldValueRegex matches. The additional check of the oldValueRegex is important as sometimes the structure of a project's endpoints does not guarantee that every "items" endpoint follows the structure of "items/{{itemId}}".

Given the following configuration in replacements.json, these URLs should be converted to these values:
pathReplacements: [ { part: 'items', oldValueRegex: '^\\d+$', newValue: '{{itemId}}' } ]

• "items/1" becomes "items/{{itemId}}"
• "items/cloneItem" is unchanged
• "items" is unchanged
• "items/1/child-1" becomes "items/{{itemId}}/child-1"

For Postman, the request.url.path array also needs to have the element containing this ID updated.

"path": [ "", "items", "1" ]

becomes:
"path": [ "", "items", "{{itemId}}" ]

Shorter names

The URL is used for the name and can be quite long, e.g.

http://localhost:8080/items/1/process?command=increase

It would improve readability and look nicer if just used the path from URL is used the name, e.g.

items/1/process