In this article:


What is RepreZen API Docs for Confluence?


RepreZen is currently beta testing a solution for API documentation on the Atlassian Confluence platform.


The solution is currently packaged as a generator module, called a GenTemplate, included in RepreZen API Studio. From a source OpenAPI 3.0 document, API Docs for Confluence generates a complete API reference page in Confluence markup format. You can publish the documentation manually by copying and pasting the generated content into the Confluence markup editor. Or you can automate publishing with the Confluence REST API.


The current beta release is first step towards a robust, enterprise-ready solution for API documentation and collaboration on Confluence. Watch this space!


Can I see some examples?

Sure! Here are two to start with:

Why not just embed a standard HTML API documentation format? 

There are some available options for embedding static or interactive HTML-based API documentation. But these formats aren't designed specifically for Confluence, and don't take full advantage of the integrated, collaborative environment of a Confluence wiki. 


Some of these advantages are evident even with the first beta release of API Docs for Confluence. For example, text formatting and page layout are consistent with the rest of your Confluence space, even if you've made changes to the default styles. And because API Docs for Confluence uses the native Confluence content model, users can post inline comments and create issues right from the text selection popup:



Other benefits will emerge as we continue to optimize the API docs format to make full use of the Confluence platform and ecosystem. Is there a particular integration you want to see with a Confluence feature or plugin? Check into the Suggestions community forum and let us know!

What Confluence products and OpenAPI versions does it work with?


OpenAPI 3.0 is supported as the source for the API Docs for Confluence code generator. Other OpenAPI versions or other API description formats may be supported in future releases.


API Docs for Confluence can be configured to generate markup that works with recent releases of Confluence Cloud, Server, and Data Center. The following format configurations are possible with the current beta release:

  • Confluence Server or Data Center with the HTML Macro
    This is the default configuration. The generated markup will contain embedded 
    {HTML} macros that will render correctly only if your Confluence administrator has 
    enabled the HTML macro
     in the Plugin Manager. Please note that the HTML macro cannot be enabled on Confluence Cloud.

  • Confluence Cloud with Adaptivist Content Formatting for Confluence

    This configuration is also supported, by setting confluenceProduct to CONFLUENCE_CLOUD in the .gen configuration file.

    Content Formatting Macros for Confluence is a popular plugin for Confluence Cloud, available from Adaptivist on the Atlassian Marketplace. It provides {div} and other macros that API Docs for Confluence can use to provide rich HTML and CSS formatting on Confluence Cloud.

  • Minimal Confluence Configuration
    If you don't have the {HTML} or {div} macro available, you can set availableMacros to PRODUCT_MINIMAL in the .gen configuration file. This will generate markup that uses only the macros and markup that are enabled in a default Confluence configuration. The generated markup will not have all of the rich formatting provided by the {HTML} and {div} macros, but it should render without errors, unless your Confluence administrator has explicitly disabled some of the plugins that are available by default on Confluence.


So, it's a beta. What's working and what's not working? 

We're starting the beta with a minimal feature set and some known issues. From there, we'll be releasing frequently with new features, improved design, and bug fixes.

The Announcements community forum for the API Docs beta will have updates with each release, so you can track our progress. 


How can I try it?


Users of RepreZen API Studio 1.6.19 and later have access to a new GenTemplate called RepreZen API Docs for Confluence. This GenTemplate works with the GenFlow framework, but is not part of the standard set of free, open source GenTemplates included in GenFlow. 


To generate API Docs for Confluence from your OpenAPI 3.0 document:

  1. Install RepreZen API Studio and activate a free trial or paid subscription.

  2. Open a RepreZen project or create a new one to contain your OpenAPI documents and GenTargets.

  3. Open or create an OpenAPI 3.0 document to describe your API.

    NOTE: API Docs for Confluence does not currently work with OpenAPI 2.0 documents.
     
  4. Create a new GenTarget using the New GenTarget command in the toolbar or dashboard, and select RepreZen API Docs for Confluence as the GenTemplate. API Studio will create the GenTarget in your project, and show the .gen configuration file.

  5. Configure the GenTarget according to your Confluence product and available macros, then save the .gen file.

    NOTE: Please see above for information on the configuration options for Confluence Cloud, Server, or Data Center, with or without formatting macros.

  6. Click the Generate button in the toolbar. By default, API Studio will place the generated markup into a *-confluence-markup.txt file in a ./generated subfolder under the GenTarget folder.


To Publish the Generated API Documentation to Your Wiki        

  1. Create a new page on the wiki, and add a page title.

  2. Open the markup editor. In the formatting toolbar, click the 'Insert more content' drop-down menu, shown with a '+' plus sign on the right side of the toolbar. From the drop-down menu, choose 'Markup'.  If you see a dropdown list with Confluence wiki and Markdown options, make sure it is set to Confluence wiki.

  3. Copy and paste the generated confluence markup from the *-confluence-markup.txt file into the markup editor on the left side of the dialog box, and click Insert.

  4. Click Publish. 


Can I generate Confluence markup from the command line or from my CI/CD platform?


Yes. 


API Docs for Confluence is packaged as a GenTemplate, which is a code generation module in the GenFlow framework. So you get the same benefits of simplified YAML configuration, preprocessing with KaiZen OpenAPI Normalizer, and generation from any environment that supports Maven or Gradle builds. 


However, unlike the GenTemplates built into GenFlow, API Docs for Confluence is not open source, so it cannot be deployed to Maven Central. Here's how API Studio supports code generation from the API Studio IDE and the command line:

  • When you create a new GenTarget using API Docs for Confluence, API Studio copies the required GenTemplate JAR to a /lib folder in your project.  

  • When you build the project, 
    addjars-maven-plugin includes the JAR in your classpath. The 
    addjars-maven-plugin, provided by Google Code, automatically installs the jar into the local repository, and adds it to the list of project's dependencies.

You'll see the addjars configuration in the GenTarget POM:


<properties>
  <project.lib.dir>C:/Users/Miles/MyWorkspace/MyProject/lib</project.lib.dir>
  <shared.gentemplates.dir>C:/Users/Miles/MyWorkspace/shared/GenTemplates</shared.gentemplates.dir>
</properties>

...

<plugin>
  <groupId>com.googlecode.addjars-maven-plugin</groupId>
  <artifactId>addjars-maven-plugin</artifactId>
  <version>1.0.5</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>add-jars</goal>
      </goals>
      <configuration>
        <resources>
          <resource>
            <directory>${shared.gentemplates.dir}</directory>
          </resource>
          <resource>
            <directory>${project.lib.dir}</directory>
          </resource>
        </resources>
      </configuration>
    </execution>
  </executions>
</plugin>


If you want to be able to generate documentation on continuous integration build servers, or on any machine other than your development workstation, you should commit the jar(s) in the /lib folder to version control. So now your project is self-contained, with the API Docs for Confluence GenTemplate jar included in the /lib folder, and the GenTarget POM configured to include it in the classpath. 


Support and Feedback

The New Community Forums we've set up for this beta are waiting for your suggestions, questions, and problem reports. This is the place to engage with RepreZen and with other beta testers.


We need your feedback to make RepreZen API Docs for Confluence beautiful, powerful, and complete!


And with your expertly designed APIs and documentation, RepreZen API Studio and API Docs for Confluence are here to help make your API clients happy, and make you and your team look like champions. :-)