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.
Table of Contents
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.
{
"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": []
}
The DITA-OT postman plug-in has been tested against DITA-OT 3.x. It is recommended that you upgrade to the latest version.
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.
- Download the
dita-ot-4.2.zip
package from the project website at dita-ot.org/download - Extract the contents of the package to the directory where you want to install DITA-OT.
- 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. - Download the
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
- 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.
To download a copy follow the instructions on the Install page
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.
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