The first API Docs for Confluence beta release is here!

We're excited to introduce a new solution for the API developer community. 

API Docs for Confluence is the first API documentation publishing solution designed specifically for Confluence. We are just getting started, but we really like the direction this is taking, and we think you will too.

Read the intro article here for the overview and examples. As promised, here's a brief overview of the current functionality, known issues, and future roadmap:

Features in the First Beta

  • Generate API documentation in Confluence markup format from OpenAPI 3.0 in RepreZen API Studio. 
  • Targets Confluence Server and Data Center with optional formatting enhancements using the Atlassian HTML macro.
  • Targets Confluence Cloud with optional formatting enhancements using the Adaptivist Content Formatting Macros for Confluence.
  • Info Object metadata in a header section, preceding the table of contents. 
  • Info description 
  • Tagged and Untagged operation groups
  • Color-keyed operation panel with request and response details
  • Basic properties table for object-typed requests and responses. 
  • Converts CommonMark markdown in description properties to Confluence markup.

Known Issues and Limitations

  • API Components to be completed
    • Security Schemes and Security Requirements
    • Links
    • Callbacks
    • Example Messages
    • Servers
    • External Documentation
    • Multiple media types in request and response
  • Complete data type format
    • Provide element type for all arrays.
    • Specialize property table layout for primitive and  array values. 
    • Include constraints and format values in property table.
  • Other improvements
    • Escape special characters
    • Translate or pass through a subset of embedded HTML.

Product Roadmap

This is a brand new project, and remains fluid as we are exploring possibilities, learning, and gathering feedback. Here is a preliminary, high-level roadmap: 

Phase 1: Complete Documentation Format

Our immediate priority is to provide complete representation of all relevant API features, and optimize the layout and styling. We expect rapid evolution in this phase, with design improvements coming in on a weekly basis. 

Phase 2: Automated Publishing

If publishing and updating through the Confluence REST API is an option for our enterprise users, we'll provide automation to publish documentation to your Confluence space. 

Automation also opens some possibilities for the generated content, such as more granular multi-page formats that would be too cumbersome to create by manual copying-and-pasting of the generated markup. 

Phase 3: Confluence Cloud Service

Pending further evaluation, we would like to offer API Docs for Confluence as a plugin on the Atlassian Marketplace, separate from RepreZen API Studio. Content generation from OpenAPI would run on our own cloud-hosted service. 

Phase 4: Confluence Server and Data Center

Once the Cloud Service is at a stage of proven stability and performance, we will explore offering API Docs for Confluence as a subscription plugin for Confluence Server and Data Center on the Atlassian Marketplace. 

We will post further details as our product strategy comes into focus.

Login or Signup to post a comment