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 and the converts the JSON to DITA. 

{
  "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

Run the plug-in installation commands: 

dita install fox.jason.extend.css
dita install fox.jason.passthrough
dita install fox.jason.passthrough.postman

The dita command line tool requires no additional configuration.

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.