Postman Plug-in

This is a DITA-OT Plug-in used to auto-create valid DITA-based REST API documentation. The documentation can be generated directly from a Postman Collection file and processed as if it had been written in DITA.

Background

Postman is a software development tool which a developer can use to build, publish, document, design, monitor, test and debug their REST APIs. More information about Postman can be found at postman.com.

This plugin processes a Postman collection to Pandoc markdown, and the converts the markdown to DITA using the Pandoc DITA-OT Plugin allowing the generation of PDF API documentation. 

{
  "name": "Obtain Entity Data by id",
  "request": {
    "method": "GET", "header": [],
    "url": {
      "raw": "http://{{orion}}/v2/entities/urn:ngsi-ld:Store:001?options=keyValues",
      "protocol": "http",
      "host": ["{{orion}}"],"path": ["v2","entities","urn:ngsi-ld:Store:001"],
      "query": [
        {
          "key": "options", "value": "keyValues",
          "description": "* `keyValues` option in order to get a more compact ...",
        },
        {
          "key": "type", "value": "Store", "disabled": true,
          "description": "Entity type, to avoid ambiguity in case there are ..."
        },
        {
          "key": "attrs", "value": "name", "disabled": true,
          "description": "Ordered list of attribute names to display"
        }
      ]
    },
    "description": "This example returns the context data of `store1`..."
  },
  "response": []
}
Figure 1. Sample Postman
Figure 2. Postman PDF Output

Install

This plug-in needs Pandoc running on user's machine to function correctly. It also requires the presence of the xmltask jar to edit XML files as part of the ANT build. It therefore requires a series of commands to install the relevant plug-in dependencies and configure Pandoc.

Run the plug-in installation commands: 

dita install https://github.com/doctales/org.doctales.xmltask/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.extend.css/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough.pandoc/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough.swagger/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough.postman/archive/master.zip

The dita command line tool requires no additional configuration.

Installing Pandoc

To download a copy of Pandoc follow the instructions on the Install page.

Usage

To mark a file to be passed through for Postman processing, label the <topicref> with @format="postman" within the <map> as shown: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
    ...etc
    <appendices toc="yes" print="yes">
      <topicmeta>
        <navtitle>Appendices</navtitle>
      </topicmeta>
      <appendix format="postman" href="postman_collection.json"/>
   </appendices>
</bookmap>

The additional file will be converted to a *.dita file and will be added to the build job without further processing. Unless overridden, the @navtitle of the included <topic> will be the same as root name of the file. Any underscores in the filename will be replaced by spaces in title.