It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Documenting REST APIs using Confluence

Tommy Holm Jakobsen Mar 26, 2015


We need a tool documenting our public REST API (ASP.NET Web API 2.0), and I've been looking for informations about whether or not Confluence is a good choice for this task.

While it would be nice if the documentation could be autogenerated from our source code, or from a swagger specification, it's not a strict requirement.

Does anyone have any experience writing REST API documentation style in Confluence? Are there any specific templates with a fit layout, or how do you write your documentation?

10 answers

3 votes
Aaron Knight Apr 08, 2016

I am quite late to this question, but I stumbled across this question via search, and others may in the future as well. I recently had this issue myself, and after finding no good out of the box solutions to integrate Swagger with Confluence, I wrote a library called Swagger Confluence.

If you document your REST API with Swagger as you suggested, and you would like a copy of the API documentation in Confluence, this project will automate your ability to do that. I wrote it for Java + Gradle, but I also provided a Command Line version that should be embeddable into any language / tool.

Using the library, you could make it publish updated documentation to Confluence as part of a Continuous Integration or deployment process, for example. Since it is written in Java, you would need to run the publisher with Java, but you could use it with any language as long as you have a Swagger schema.

On the linked homepage, there is a live demo that shows several available display options.

Note: For Confluence Cloud in particular, you need to make sure the REST API is enabled for your instance For stand-alone Confluence, this is enabled by default. The library works via the REST API so it will fail if the API is not available.

Full disclosure: I am the author of the library; I wrote it after having a similar problem myself. I released it as open source software in hope that it would be useful to others.

Andreas Stenius Nov 04, 2017

Thank you so much for sharing this. Was exactly what I was looking for.

I expect to make some tweaks, since I want to use page properties for all routes so I can have an overview page with all routes on them for brevity.

But this beats having to implement it all from scratch.

0 votes


You might take a look at this plugin: Confluence JavaDoc Macros


Rafael Pereira

Tommy Holm Jakobsen Mar 30, 2015

Thanks for your post Rafael. However, that looks more like a class-reference style of documentation. Also, it's not available for Confluence Cloud. Any other ideas?

0 votes
Ali Apr 29, 2016

I am looking for the same thing.  

0 votes
Hamish Moffatt May 09, 2016

Me too. A few things I've found:


I'm using Confluence Server though, and I'd prefer to edit within Confluence.

0 votes
Scott O'Hara May 24, 2016

re: Confluence Open API Documentation....   a Confluence Server version has been developed and is currently awaiting Marketplace approval by Atlassian (hopefully in the next few days).

Pricing starts at $10/year (for 10 user), or $50/year for all other user tiers.

0 votes
Hamish Moffatt May 24, 2016

Great. Does it link to/include, or do you plan to add, the Swagger editor?

0 votes
Scott O'Hara May 24, 2016

Only swagger-ui is supported at this stage.

0 votes
Hamish Moffatt May 31, 2016

Any news on when the Server add-on will be available?

0 votes
Scott O'Hara May 31, 2016

Still waiting on Atlassian Marketplace approval, I'm afraid.

From previous experience, approval normally takes between 1-2 weeks.

The server version of Confluence Open API Documentation was submitted on May 17; so it has been just over two weeks in pending approval status, which hopefully means it should be any day now.

0 votes
Scott O'Hara Jun 03, 2016

The Server version has been approved, and is now available in the Marketplace.

Paul LaBarbera Jun 01, 2017

We need to render RAML, not Swagger, files. Do you have any plans to support RAML with this plugin?

Scott O'Hara Jun 01, 2017

Unfortunately no...the plugin uses Swagger UI, which is designed specifically for the Swagger specification only. 

Suggest an answer

Log in or Sign up to answer
This widget could not be displayed.
This widget could not be displayed.
Community showcase
Published in Confluence

Confluence CVEs and common questions

Two vulnerabilities have been published for Confluence Server and Data Center recently: March 20, 2019 CVE-2019-3395 / CVE-2019-3396 April 17, 2019 CVE-2019-3398 The goal of this article is...

956 views 0 19
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you