Postman Plugin for DITA-OT

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.

▶️ Video from DITA-OT Day 2019

Table of Contents

• Background
• Install
  • Installing DITA-OT
  • Installing the Plug-in
  • Installing Pandoc
• Usage
• License

Background

Postman is a software development tool which a developer can use to build, publish, document, design, monitor, test and debug their REST APIs.

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.

Sample Postman Request

{
    "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": []
}

Sample DITA Output

Install

The DITA-OT postman plug-in has been tested against DITA-OT 3.x. It is recommended that you upgrade to the latest version.

Installing DITA-OT

The DITA-OT postman plug-in is a file reader for the DITA Open Toolkit.

• Full installation instructions for downloading DITA-OT can be found here.

  1. Download the dita-ot-4.2.zip package from the project website at dita-ot.org/download
  2. Extract the contents of the package to the directory where you want to install DITA-OT.
  3. Optional: Add the absolute path for the bin directory to the PATH system variable.

  This defines the necessary environment variable to run the dita command from the command line.

curl -LO https://github.com/dita-ot/dita-ot/releases/download/4.2/dita-ot-4.2.zip
unzip -q dita-ot-4.2.zip
rm dita-ot-4.2.zip

Installing the Plug-in

• Run the plug-in installation commands:

dita install https://github.com/jason-fox/fox.jason.extend.css/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 follow the instructions on the Install page

Usage

To mark a file to be passed through for Postman processing, label it with format="postman" within the *.ditamap 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.

License

Apache 2.0 © 2019 - 2024 Jason Fox

The Program includes the following additional software components which were obtained under license:

• json-simple-1.1.1.jar - https://github.com/fangyidong/json-simple - Apache 2.0 license