New July 2019 Release, with Auto-Publishing to Confluence Server!

RepreZen API Studio release 1.6.20 is now available, with a new API Docs for Confluence beta built-in. This is a significant re-implementation of the code generator, and introduces automated publishing of the generated API Docs to Confluence Server or Confluence Data Center. 


We learned that the approach we took in the first beta release -- generating Confluence Wiki markup  with embedded macros -- didn't work in some Confluence Server environments. To take full control over the content representation in Confluence, we're now generating Confluence Storage Format and publishing the generated content directly through the Confluence REST API.


We were planning to do this after finishing the API documentation format, but it turned out to be a prerequisite, so it's now phase 1 in our product roadmap: 


  • Phase 1: Automated Publishing to Confluence Server (Complete)
    Publish generated API documentation to a designated Confluence space, with configuration options for the Confluence server, space, page title, parent page, proxy, and user account credentials.

Note: In this beta release, API Docs for Confluence only supports automated publishing to Confluence Server or Data Center. But you can still publish to Confluence Cloud using the Confluence Source Editor, and we plan to support publishing to Confluence Cloud in a later release. 


  • Phase 2: Complete Documentation Format
    Our next 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 every week or two.

  • Phase 3: Confluence Cloud Service Solution
    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 Solution
    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.


Read the intro article here for an updated guide to configuring and working with the API Docs for Confluence beta.

Features in this Beta

  • Generate API documentation in Confluence storage format from OpenAPI 3.0 in 
    RepreZen API Studio.

  • Publish to Confluence Server or Confluence Data Center using the Confluence REST API with basic authentication and an optional proxy configuration.

  • Tagged operation groups, consisting of a tag heading, description, and a sub-section for each operations assigned to the tag.

  • Untagged operation groups, consisting of a path item heading, description, and a sub-section for each untagged operation defined within that path item.
     
  • Color-keyed operation panels 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.


Join the discussion!


This forum is your community space for questions, comments, and feature suggestions. We love hearing from you, so please share your thoughts. :-)

Login or Signup to post a comment