Swagger Confluence

Introduction

The primary goal of Swagger Confluence is to simplify publishing Swagger API documentation to an Atlassian Confluence wiki. Ideally, the Gradle Plugin or CLI would be activated on the build of a schema jar, which would contain your contract-first Swagger JSON or YAML file

Many organizations use Atlassian tools such as JIRA and Confluence as part of their software development process. If an organization uses Confluence spaces for documentation, then it makes sense to be able to publish API documentation to Confluence as well. This project helps provide integration of the Swagger API documentation into Confluence.

While this was previously possible via stringing together other projects, it was not easy to drop in and use. Multiple plugins and technologies had to be glued together within to achieve the desired result, and customizing the output was cumbersome.

This project seeks to offer a one-stop drop in solution for publishing Swagger API documentation to Confluence by abstracting from the user the burden of coordinating the required third party libraries that make this possible, and exposing a variety of output options that the end user can choose from to suit their needs.

Publishing Flow

This project uses the following flow to publish to Confluence:

Your Swagger Schema -> Swagger2Markup -> AsciiDoctorJ -> XHTML -> Confluence REST API

Components

The project is current broken into three components

• swagger-confluence-core: a core shared library to handle converting and publishing the swagger schema to confluence. This shared library should be reusable by other projects
• swagger-confluence-gradle-plugin: a gradle plugin to provide seamless conversion and publishing
• swagger-confluence-cli: a command line executor for publishing to swagger docs to confluence

Requirements

To use this project, the following is required:

• A Swagger Schema (JSON or YAML)
• An Atlassian Confluence 5.x Server
• A Confluence User with access to the REST API
• Java 7 or later
• Optional: Gradle to use the Gradle Plugin

Future Goals

• Maven plugin. In the meantime, if you are a Maven user you can use Swagger Confluence CLI with the Maven Exec Plugin You can download Swagger Confluence CLI from the link in the top navigation, or resolve it as a dependency from JCenter. At this time, Swagger Confluence is not available in Maven Central. I apologize for the inconvenience.

Special Thanks

A special thanks for the following projects, who make this project possible:

• Swagger2Markup
• AsciiDoctorJ
• Jsoup
• Confluence REST API

Additional shout-outs to the following two projects - whom I tried using manually in conjunction with the above projects and their respective gradle plugins before starting this project:

• asciidoctor-confluence
• asciidoc2confluence

The XHTML->Confluence REST API portion of this library was originally inspired by the asciidoc2confluence groovy script

Also a special thanks to Tom Johnson for the Jekyll Documentation theme, which powers this documentation.

License

Copyright 2016 Aaron Knight

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.