Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jason-fox/fox.jason.passthrough.postman
Generate DITA-based REST API documentation from a Postman collection added directly to a ditamap
https://github.com/jason-fox/fox.jason.passthrough.postman
dita dita-ot-plugin postman postman-collection rest-api
Last synced: 29 days ago
JSON representation
Generate DITA-based REST API documentation from a Postman collection added directly to a ditamap
- Host: GitHub
- URL: https://github.com/jason-fox/fox.jason.passthrough.postman
- Owner: jason-fox
- License: apache-2.0
- Created: 2019-07-30T19:26:49.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-18T07:38:11.000Z (9 months ago)
- Last Synced: 2024-10-10T02:15:14.985Z (about 1 month ago)
- Topics: dita, dita-ot-plugin, postman, postman-collection, rest-api
- Language: Java
- Homepage: https://jason-fox.github.io/dita-ot-plugins/postman
- Size: 523 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Postman Plugin for DITA-OT [
](http://postmandita-ot.rtfd.io/)
[](http://www.apache.org/licenses/LICENSE-2.0)
[](http://www.dita-ot.org/4.2)
[](https://github.com/jason-fox/fox.jason.passthrough.postman/actions?query=workflow%3ACI)
[](https://sonarcloud.io/dashboard?id=fox.jason.passthrough.postman)
This is a [DITA-OT Plug-in](https://www.dita-ot.org/plugins) used to auto-create valid DITA-based REST API
documentation. The documentation can be generated directly from a [Postman Collection](https://www.getpostman.com/) file
and processed as if it had been written in DITA.
:arrow_forward: [Video from DITA-OT Day 2019](https://youtu.be/cd7XThpkivw)
[](https://youtu.be/cd7XThpkivw)
Table of Contents
- [Background](#background)
- [Install](#install)
- [Installing DITA-OT](#installing-dita-ot)
- [Installing the Plug-in](#installing-the-plug-in)
- [Installing Pandoc](#installing-pandoc)
- [Usage](#usage)
- [License](#license)
## Background
[
](https://www.getpostman.com/)
[Postman](https://www.getpostman.com/) 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](https://github.com/jason-fox/fox.jason.passthrough.pandoc) allowing the generation of PDF API
documentation.
#### Sample Postman Request
```json
{
"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](http://www.dita-ot.org/download). 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](https://www.dita-ot.org/4.0/topics/installing-client.html).
1. Download the `dita-ot-4.2.zip` package from the project website at
[dita-ot.org/download](https://www.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.
```console
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:
```console
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](https://github.com/jgm/pandoc/blob/master/INSTALL.md)
## Usage
To mark a file to be passed through for **Postman** processing, label it with `format="postman"` within the `*.ditamap`
as shown:
```xml
...etc
Appendices
```
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](LICENSE) © 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**