Supporting postman collections

[thomaseizinger]

What do you guys think about supporting postman collections? It should be possible to integrate them in a similar manner as the curl documentation, although it could be tricky because a postman collection is described in one file.
As all the classes are re-instantiated on every call, one way of doing things would be trying to deserialize the given file into a list of postman-collection-models, append current request and overwrite the given file with the updated list.
A few changes would be needed in order to properly generify classes like SnippetWritingResultHandler for them to support different output writers. The mentioned ResultHandler is currently hardcoded to use the AsciiDoctorWriter.
I am not quite sure on what is the best way to do this, since I cannot really figure out, which class should be responsible for determining in which format the request/response is going to be documented.
Although writing out postman collections is just a matter of implementing a DocumentationWriter and DocumentationActions, it does not make much sense to use them in combination with the cURL stuff. So maybe classes like CurlDocumentation should decide which DocumentationWriter should be used to write the DocumentationAction.
I would happily support the implementation of this feature request.

[wilkinsona]

Thanks for the suggestion. I'm not familiar with Postman collections. I assume this is what you're referring to? Do you know if the file format is documented anywhere?

My initial reaction is that this doesn't really fit within the scope of this project, but I can see that it might be useful to provide links to Postman collections in a getting started guide that groups together a series of operations. I'm not sure how widely used Postman is, this would certainly be more of a niche than HTML-based documentation. Also, for a hypermedia-based API, I'd want Postman to be following links rather than using hardcoded URIs. Is that possible?

it could be tricky because a postman collection is described in one file.

The infrastructure that supports documenting multiple steps in a single test might help here. While it's currently used to write separate snippets for each step, it could also provide a foundation for documenting multiple steps into a single file.

A few changes would be needed in order to properly generify classes like SnippetWritingResultHandler for them to support different output writers. The mentioned ResultHandler is currently hardcoded to use the AsciiDoctorWriter.

I have a local branch that's tackled some of this as part of supporting Markdown as an output format (#19). That work's currently on hold due to Markdown's lack of support for includes but it could be dusted off to support this if we decide it's worth doing.

[thomaseizinger]

Yes, that is the software I was referring to.

Do you know if the file format is documented anywhere?

I have not found anything but I did not invest much time into research since the file consists of a simple JSON-Array with rather small models.
I have already extracted that into entities and ran some successful tests covering the basics.

Also, for a hypermedia-based API, I'd want Postman to be following links rather than using hardcoded URIs. Is that possible?

Postman makes links in responses clickable, so you just need to hit enter again and it will execute a request to the clicked link. There is also an option to preserve headers between those clicks (useful for stuff like custom authentication tokens). I have used postman in combination with SDR and found it very easy to use.

I'm not sure how widely used Postman is, this would certainly be more of a niche than HTML-based documentation.

I think it would be a nice addition to the HTML-documentation because you can execute the request right away, just filling in the desired parameters. Postman also supports some kind of integration tests (if you support them with a donation) but I have not used them so far. I have experienced it has a very sophisticated and useful tool.

Edit: The chrome extensions (normal and packaged app) have about 1.5kk users in total.
Packaged app
Extension

[msoub]

This enhancement would be much appreciated 👍

[jrrickard]

@wilkinsona have you been working on this? I think that this would be useful for my team as we currently use a bunch of hand created Postman collections, so I'll take a stab at it this weekend if you haven't.

[wilkinsona]

@jrrickard I haven't. A PR would be much appreciated, even if it's just a foundation to build upon. Just to be clear, 1.0 is pretty much done now so this issue's targeted at 1.1.

[jrrickard]

This was a little more complex than I thought, but I have a working implementation. I'll do some polish on it and open the PR tonight hopefully and you can take a look.

[donovanmuller]

@jrrickard did you ever get around to creating that PR?
What is the general status on this issue? (coming from here)

[jlstrater]

@jrrickard I know this is an old issue, but did you get anywhere with it? If so, could you push what you have? Otherwise, I'd like to start on this issue. It would really be helpful for what I'm doing at work.

[fbenz]

I solved it for myself by creating a small npm package that does the job: https://www.npmjs.com/package/restdocs-to-postman

It can be used as a CLI tool:

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

The following article explains the tool a bit: https://medium.com/@flbenz/create-postman-collections-out-of-tests-7ee05c8c1883

[wilkinsona]

With thanks to @fbenz's blog post, I have an answer to my question above and now know that the Postman schema is documented here.