Swagger 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 Swagger file and processed as if it had been written in DITA.
Background
Swagger 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. More information about Swagger can be found at swagger.io.
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
Install
Run the plug-in installation commands:
dita install https://github.com/doctales/org.doctales.xmltask/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough/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.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 of Pandoc follow the instructions on the Install page.
Usage
To mark a file to be passed through for Swagger processing, label
the <topicref>
with @format="swagger"
within the <map>
as shown:
The additional file will be converted to a *.dita
file and will
be added to the build job without further processing. The title 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.