Using Postman as both as a test runner and API documenter

🌱 Just Getting Started
,
1

I love Postman, but I’m trying to use it both for its test running abilities and as an API documenter, and it doesn’t seem to do both at the same time without doubling the work.

For instance, I can create great API documentation by listing out all my API calls in a collection, one by one. User Create, User Edit, User Delete, Story Create, yadda. Then going to “View Documentation” on the collection.

But, when I go to “Run” collection, I only have the option to change the order, but not to, say, add two users and then share a story between them. Or create one story, create another, then delete the first, etc.

Alternatively, I could make a collection that does the “Run” better, by repeating calls, etc., but that makes for crappy documentation that’s generally out of order and repetitive.

So I’m left with making two collections; one for documentation, and one for test runs, and that’s a lot of duplication. Am I missing a way to take an “organized” collection set and test run it in a real-life way?

2

Hey @telecoms-explorer-53 :wave:

Welcome to the Postman Community! :postman:

I can’t really see another way that you could have that, it seems like having 2 Collections for those 2 different contexts would be a good thing.

One of those is the full documentation of what your API offers, showing the full implementation of the way that those individual endpoints work.

The second Collection being more of a scenario based view and highlighting certain user cases that could be handled by those documented endpoints.

That could be a duplicated Collection or you could have a forked Collection of the other one.

3

Thanks @danny-dainton ,

Yeah, I was thinking of a flow like this:
1.) You create your API documentation with full parameters explained, etc.
2.) You create a runner that is more sophisticated, using the API documention as your base. For instance, the runner would say:

  1. Take the POST user endpoint
    • set the parameter “name” to “bob”
    • send
    • test
  2. Take the POST user endpoint
    • set the parameter “name” to “jane”
    • send
    • test

In this way, you’re running tests off of pre-set calls, rather than making brand new calls for a call you’ve defined elsewhere.

I could see this being done in one of two ways. Either a more sophisticated runner, or a collection that allows you to “mirror” defined requests set up in other collections.

But, good to know this isn’t a thing so I don’t keep digging to see if it’s possible. Thanks!

4

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.