Export/Download API Documentation

[aswope]

Issue Report:

The new API documentation feature is coming along nicely! (Hopefully parameters will be added quite soon.)

HOWEVER, the main issue preventing me from taking the team to Postman and its Documentor is the reliance on always serving documentation from Postman's servers. I have to be able to deliver offline documentation to my customers. (This can be in HTML, doc, or PDF format.)

I've been emailing Claire Riley regarding this, and she requested that I open an Issue. It appears that Swagger's documentation feature is capable of doing this, but I REALLY DO NOT want to move our API workflow to using Swagger.

Alternative: Add a feature to produce API blueprint files that are compatible with Aglio or other similar blueprint-based documentor.

[sdnts]

@aswope Thanks for reporting this here! I'm marking this as a feature request! We'll look into this.

[djbf]

Just chiming in, but I'd prefer something along the lines of the proposed alternative. If Postman could export a file compatible with API Blueprint and Swagger, that'd be awesome. I'm sure there's a group of folks who wouldn't mind a RAML export filter, too.

see: https://github.com/postmanlabs/postman-app-support/issues/1744

[igorsantos07]

Any news on Blueprint import/exports?

This seems to be sort of an open standard on API documentation. While Swagger is cool, it is, many times, a PITA to integrate in your server to generate the requested files. Blueprint is a wide open tool and easy to generate doc files that later could be imported in Postman.... Could.

[omarrida]

Would love to see this feature implemented... any timeline in mind?

[godfrzero]

This isn't an API documentation-specific problem. We're working on importers/exports for the app, which will allow the collection itself to be moved around in various formats. Since the documentation is a part of the collection anyway, this information would also be available in the export. If I'm understanding your problem correctly, this should be a viable solution.

In the meantime, you can try using one of our integrations to export to various formats. (Have a look at the integrations section on the web Dashboard, and look for the APIMatic integration).

A PDF export feature for documentation is on the horizon, but there's no ETA on this yet. Keep an eye on the public roadmap.

[arman-sydikov]

Will it be compatible with GitHub Pages ?

[godfrzero]

@algakzru I'm not sure what you mean.

[arman-sydikov]

@godfrzero Will it be possible to use it as a Jekyll template like https://github.com/CloudCannon/aviator-jekyll-template or https://github.com/Wiredcraft/carte ? For publishing it to GitHub Pages of my project, for example http://algakzru.github.io/api

[godfrzero]

From the API Documentation export, I doubt it. I'm assuming that these templates require the data to already be in some specified format. The correct way to approach this would be to use the exported collection (perhaps using the GitHub integration to get it syncing with GitHub), adding an interface/transformer layer between the raw JSON and the template, and using the output of that layer to generate the template. This is something that you can already do right now.

[stixaw]

+1

[oscarguinane]

+1

[oscarguinane]

Hey all,

You can use httrack to copy your API locally in HTML for offline viewing with this script I made:

# Install httrack.
brew install httrack # OSX

# Create the destination directory.
mkdir -p ~/Desktop/websites/API/
cd ~/Desktop/websites/API/

# Download the relevant links into the directory.
httrack https://documenter.getpostman.com/view/000/ABC \
        http://cdn.ravenjs.com/3.26.2/raven.min.js.map \
        https://documenter.getpostman.com/api/examples/000/ABC \
        https://documenter.getpostman.com/api/collections/000/ABC -r3 +*

# Remove unnecessary files.
rm -r www.bohemiancoding.com www.sketchapp.com www.w3.org \
      hts-cache cookies.txt hts-log.txt backblue.gif fade.gif

# Remove `.json` from the collection names.
mv documenter.getpostman.com/api/collections/000/ABC.json \
   documenter.getpostman.com/api/collections/000/ABC;
mv documenter.getpostman.com/api/examples/000/ABC.json \
   documenter.getpostman.com/api/examples/000/ABC

# Fix the `/api` directory links.
gsed -i 's/\/api\//..\/..\/api\//g \'
        documenter.getpostman.com/docs-assets/js/production.min.js

# Open the index file!
open index.html

### Make sure to disable `file://` CORS ###
### In Safari preferences, turn on the develop menu. From the new menu item, turn on `Disable Local File Restrictions`
### In Chrome, open the application with the local security flag turned off.
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --allow-file-access-from-files

[pdsorensen]

Thanks for looking into the feature request! +1

If it's possible to generate the documentation as static assets, it would also allow for the option to serve documentation from non-domain locations such as s3.

Also, any plans to support documentation publishing or doc generation through the newman cli?

[shaunwarman]

Static assets would be ideal. This would allow for a folder in a repo to get served via github pages or similar. Close to where postman collections are often stored.

[rakibulhaq]

after two years since the issue opened, is there any update about when this feature may come around?

[21anujashah]

+1

[tomsihap]

+1 this is becoming urgent for quite a necessary feature

[jordangottlieb-ych]

We need this

[Cedric4real]

+1

[yenkuanlee]

+1

[nao3301]

+1

[Absynth723]

+1 I'm evaluating Postman and I gotta say I was dumbfounded when I noticed that documentation cannot be exported to PDF.

[21anujashah]

Right now, I am doing print as pdf and saved in the directory . I am waiting for this feature

[Askill]

+1 Any news on this?

[mecorre1]

+1 Any date for the feature?

[amolv]

yes, we need offline docs!

[mauriceackel]

+1

[grantm009]

I paid for the subscriptions to Postman thinking that the custom domain feature was for documentation - only to discover today that it is not and it looks like it is not possible. Furthermore it does not appear that Postman plans to provide this capability having made such a marketing fuss about how great their documentation is - we can't get it to our customers. Very disappointing and would not have subscribed if I had realised.

[1440530275]

+1

[kuige]

It's 2020 now, this feature is still not available!

[zanderwar]

+1 we have to move away from Postman since this feature does not exist. The documentor is outstanding but a bit useless when you can't do anything with it.

Literally wasted 2 weeks writing up the documentation just to discover that I'm wasting time when it complete enough to distribute.

[AtillaAcar]

We liked the document creation part of Postman. However, we need to export them as pdf. @zanderwar were you able to find a better tool for documentation?

[Raja-Simha]

As we look into this request, I would like to start a conversation to help us understand why you need to export documentation as PDF or static assets. Anything around your team workflows or why this cannot be achieved with the current feature set will help us find a solution that fits most. @AtillaAcar @absynth47215 @shaunwarman or anyone looking for this feature, do share your thoughts.

[Absynth723]

My usecase is exporting a snapshot of our API documentation to give to my customers. HTML is too unwieldy for this, and I cannot count on them using Postman as well, some do and some don't. I haven't found a way to do this with Postman yet.

[aswope]

Because we have to deliver it to our customers and other API subscribers, who may not have, or want, Postman access online.

##################################################################################### Scanned by MailMarshal #####################################################################################

[AtillaAcar]

First of all thank you for your consideration.

When I give api documentation to my customers with Postman html docs, I think these apis will be visible to all customers. I have different customers and I give them some collections and not giving them some.

In addition, postman documents have no authentication for customers, I think it would be safer to send them with pdf.

On Fri, Feb 21, 2020 at 5:20 PM aswope notifications@github.com wrote:

Because we have to deliver it to our customers and other API subscribers, who may not have, or want, Postman access online.

#####################################################################################

Scanned by MailMarshal #####################################################################################

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/postmanlabs/postman-app-support/issues/3438?email_source=notifications&email_token=ALGBUKHCPMHDT5NIBLLPCCLRD7PJTA5CNFSM4DYCMJX2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEMS3BUY#issuecomment-589672659, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALGBUKC2UA2W5BGP7KO5ISTRD7PJTANCNFSM4DYCMJXQ .

-- Atilla Acar Yazılım Ekip Lideri Monad Yazılım ve Danışmanlık Hacettepe Üniversitesi Beytepe Kampüsü Teknokent 1 Nolu AR-GE Binası No : 3 06800 BEYTEPE - ANKARA

Tel : +90 312 299 2360 Faks : +90 312 299 2358 www.monad.com.tr

[zanderwar]

We need to deliver a PDF for tenders and to provide it as a downloadable file on our website.

[jordangottlieb-ych]

We absolutely need to be able to export portable documents for offline use, that only show a subset of the API, for example:

• Exposing a few endpoints to a 3rd party
• Appending API updates only to release documentation
• Creating developer docs for teams that only need access to part of an API
• ...

[prmichaelsen]

It would be nice if postman stored its collections in plain text in the first place so there is no need to export. Plain text would allow one to check in all postman configurations to git.

3563

[followben]

Our api docs need to exist as a static site that can be hosted on our own servers (and as a pdf for an internal printed manual) for security and legal reasons. We'd love to be able to use Postman documentation, but presently can't because of this requirement.

[korylus]

We would also like to be able to export to a static site so we can host the docs ourselves, particularly as we don't want to be limited to using a subdomain like https://api-docs.example.com, as is the only option with Postman custom domains

[ljdev1]

+1 for this feature request! The ability to export the documentation to a number of formats would be ideal... html, pdf, markdown, and more!

[jwbanning]

I recently came across > https://github.com/aubm/postmanerator. Hope this helps a couple people.

[karthiks3000]

I just finished creating my own tool to convert the collection to an html doc similar to what postman has - https://github.com/karthiks3000/postman-doc-gen

hope this helps..

[thesteve0]

I would also vote for an export from postman hosting it. I want a process where I can use postman to generate the docs and then host on my developer portal. Having you folks host the doc is a non-starter for my company.

[zanderwar]

We moved all our API's from Postman to Swagger + ReDoc as it makes privately hosting the docs very simple. Hopefully we'll move back to Postman if they consider this adding this but they are open-source after all so my expectations remain low on the versatility they decide to collaboratively add to their software.

[msageryd]

+1

[Mackzwellz]

+1. Our use case for collections is not to document the API itself (there are solutions for that already, e.g. SwaggerUI / ReDoc), but user experience flows (effectively, request chains). We would like be able to have static html files generated along with static resources, so we could host them on our company's internal Github Enterprise's Git Pages. This could be an option next to collection export button, or a button next to "Publish" when editing collection in documentation mode. Would be nice if there was support for multiple examples for each request, and ability to see pre-request scripts and tests for each request as well.

I searched for unofficial solutions, but none of them are sophisticated enough, and I feel that should be an out-of-the-box feature. Some folks on StackOverflow suggest to print to PDF or download the collection page after publishing it... But that is suboptimal at best.

List of available unofficial solutions:

• https://github.com/aubm/postmanerator
• https://github.com/thedevsaddam/docgen
• https://github.com/karthiks3000/postman-doc-gen
• https://github.com/JakeWorrell/docodile
• https://github.com/jason-fox/fox.jason.passthrough.postman (requires DITA-OT)

[verschuur]

Our use case is roughly the same as @followben posted on 18 Mar 2020. We need to be able to share our documenation with a set of clients. For legal and security reasons, we cannot add them all to a team, and having a public link is a risk factor. We need to be able to either generate HTML docs and host them on our own server, or generate a document which we can share.

[SajjadArifGul]

we need this feature ASAP