Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jason-fox/fox.jason.passthrough.swagger
Generate DITA-based REST API documentation from a Swagger file added directly to a ditamap
https://github.com/jason-fox/fox.jason.passthrough.swagger
dita dita-ot-plugin rest-api swagger swagger-documentation
Last synced: 30 days ago
JSON representation
Generate DITA-based REST API documentation from a Swagger file added directly to a ditamap
- Host: GitHub
- URL: https://github.com/jason-fox/fox.jason.passthrough.swagger
- Owner: jason-fox
- License: apache-2.0
- Created: 2019-07-22T06:30:26.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-18T07:37:02.000Z (9 months ago)
- Last Synced: 2024-10-10T02:21:28.459Z (about 1 month ago)
- Topics: dita, dita-ot-plugin, rest-api, swagger, swagger-documentation
- Language: XSLT
- Homepage: https://jason-fox.github.io/dita-ot-plugins/swagger
- Size: 23 MB
- Stars: 6
- Watchers: 2
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Swagger Plugin for DITA-OT [
](http://swaggerdita-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.swagger/actions?query=workflow%3ACI)
[](https://coveralls.io/github/jason-fox/fox.jason.passthrough.swagger?branch=master)
[](https://sonarcloud.io/dashboard?id=fox.jason.passthrough.swagger)
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 [Swagger](https://github.com/swagger-api) 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
[
](http://swagger.io/)
[Swagger](https://swagger.io/) is an open-source software framework backed by a large ecosystem of tools that helps
developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger
UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.
[Swagger2Markup](https://github.com/Swagger2Markup/swagger2markup) converts a Swagger JSON or YAML file into one or more
AsciiDoc or GitHub Flavored Markdown documents which can be combined with hand-written documentation. The Swagger source
file can be located locally or remotely via HTTP. Swagger2Markup supports the Swagger 1.2 and 2.0 specification.
Internally it uses the official swagger-parser and my markup-document-builder.
This plugin processes the Swagger file 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)
#### Sample Swagger Endpoint
```json
"paths": {
"/pet": {
"put": {
"tags": [ "pet" ],
"summary": "Update an existing pet",
"description": "",
"operationId": "updatePet",
"consumes": ["application/json", "application/xml"],
"produces": ["application/xml", "application/json"],
"parameters": [
{
"in": "body", "name": "body", "required": true,
"description": "Pet object that needs to be added to the store",
"schema": { "$ref": "#/definitions/Pet" }
}
],
"responses": {
"400": {"description": "Invalid ID supplied"},
"404": {"description": "Pet not found"},
"405": {"description": "Validation exception"}
},
"security": [
{
"petstore_auth": ["write:pets","read:pets"]
}
]
}
},
```
#### Sample DITA Output
> 
## Install
The DITA-OT Swagger 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 Swagger 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.passthrough.pandoc/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.swagger/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
For DITA processing, a swagger file can be defined in either `json` or `yaml` format.
To mark a file to be passed through for **Swagger** processing, label it with `format="swagger"` 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 overriden, 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:
- swagger2markup-cli-2.0.0.jar - https://github.com/Swagger2Markup/swagger2markup - **Apache 2.0 license**