In this article:

What is RepreZen API Docs for Confluence?

API Docs for Confluence, currently in beta, is the first OpenAPI documentation solution designed from the ground up to take full advantage of Confluence as a collaborative content management platform. Your OpenAPI documents will present with a clean, modern look that's easy to read, easy to navigate, and makes your APIs easy to learn and use.

And with its colored panels, intuitive visual hierarchy, and native Confluence formatting that works seamlessly with your custom stylesheets, it's pretty easy on the eyes too. ;-)

RepreZen API Studio 1.6.20 and later releases now include API Docs for Confluence as a code generation module, called a GenTemplate. From a source OpenAPI 3.0 document, API Docs for Confluence generates an API reference in Confluence storage format, and optionally publishes the generated content directly to Confluence Server or Confluence Data Center.

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

Can I see some examples?

Sure! Here are two to start with:

What you see in these examples is just a start. We'll be making significant improvements and adding new features to API Docs for Confluence as we progress through the beta phase to our first GA release.

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 an early 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.

Confluence Server and Confluence Data Center are supported by the automated publishing option. 

Confluence Cloud also works with the generated format, but you'll need to paste it into the Confluence Source Editor or implement your own publishing code using the Confluence REST API. We will aim to support automated publishing to Confluence Cloud in a later release.

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.20 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 with RepreZen API Docs for Confluence as the GenTemplate. Start by clicking 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 automated publishing in the GenTarget to publish to the generated content to a space on Confluence Server or Data Center.  See Configuring Automated Publishing to Confluence below for a detailed guide to the .gen file options.
  6. Click the Generate button in the toolbar. By default, API Studio will place the generated markup into a *-confluence.txt file in a ./generated subfolder under the GenTarget folder.

Configuring Automated Publishing to Confluence

By default, the GenTarget will simply generate the content to a text file. To publish to Confluence, you'll need to update these settings in the .gen configuration file:

  • publishToConfluence - a Boolean property to indicate whether you want to publish the generated API documentation to Confluence. Set this to 
    true
     to enable publishing.
  • confluenceRestUrl - the base URL of the Confluence REST API, required if publishToConfluence is TRUE. Normally, this is the URL used to access Confluence, without the space key and page segments, and with '/rest/api' appended to the path. For example: https://technology.bigco.com/confluence/rest/api
  • spaceKey - Identifies the Confluence Space to contain the published API documentation page. Required if publishToConfluence is TRUE. 
    • You'll see the space key in the URL of your Confluence wiki pages, immediately after the /spaces/ segment. In the following URL, "modsquad" is the space key:
      https://modelsolv.net/confluence/spaces/modsquad/overview 
    • The Confluence account configured in the confluenceUserName and confluencePassword properties, described below, must have full permissions to create and update pages in the configured Confluence space. If you're not sure, you can verify this by logging into Confluence with those same credentials, then creating and updating a page.
  • pageTitle - the title of the API documentation page to be published. Required if publishToConfluence is TRUE. This is the title that will appear in the page header (separate from the main content area), and in any automatically generated links to the page.
  • parentPageTitle - optionally specifies the title of a page that will contain the published API documentation page as its child. Note that parentPageTitle is used only if publishToConfluence is TRUE, and only when the API documentation page is first published to Confluence. If the parentPageTitle is null or unspecified, the API documentation page is published at the top level within the Confluence space.
  • confluenceUserNameEnvar and confluencePasswordEnvar - the names of environment variables holding the Confluence username and password, respectively, to authenticate and interact with the Confluence REST APIs. Required if publishToConfluence is TRUE.
    • Environment variables are currently the only supported way to provide user credentials to API Docs for Confluence. Later releases will allow the use of Java system properties, and possibly other ways to supply credentials.
    • You can define the default CONFLUENCE_USER_NAME and CONFLUENCE_PASSWORD environment variables, or you can specify alternative environment variable names that will hold the Confluence user account credentials.
    • The variables must be defined in the environment of the running process that will launch the generator. Once you have set these environment variables in your primary OS environment, you will usually need to shut down API Studio completely restart. Using File > Restart is not recommended for this purpose. Use File Exit, ensure that the process is no longer running, and then restart.

      See the article Working with Environment Variables in API Studio for more information.
    • The specified Confluence user account must have full permissions to create and update pages in the configured Confluence space. If you're not sure, you can verify this by logging into Confluence with those same credentials, then creating and updating a page.
    • The Confluence Server API works with basic authentication, which passes an HTTP header with the API request, containing the username and password you provide in a base64 encoded format. 

Caution! 

Basic authentication does not encrypt the username and password; it relies on transport-level security (such as HTTPS) and other outside layers of defense to prevent compromising user credentials or other sensitive information. Make sure you are taking appropriate precautions, in line with any required policies and practices in your network environment.

  • proxyUrl - optional URL of an HTTP proxy to be used for interactions with the Confluence Server REST API. Only the host and port components of the URL will be used to configure the proxy settings in the REST client. Path, query, and fragment components are not supported.
  • proxyUserNameEnvar and proxyPasswordEnvar- optional names of environment variables holding the username and password for authentication with a proxy. 
    • Please note the detailed information provided above, related to confluenceUserNameEnvar and confluencePasswordEnvar. These same considerations apply to proxyUserNameEnvar and proxyPasswordEnvar as well.
    • If the specified proxyUserNameEnvar is defined and proxyUrl is also specified, the REST client will authenticate with the proxy for communication with the Confluence API. Otherwise, the REST client will use the proxy (if specified) without authentication.
    • If proxyUrl is specified and the proxyUserNameEnvar resolves to a username, proxyPasswordEnvar is also required and must resolve to a password.

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. :-)