How to post Swagger API documentation to Atlassian

Question

I'm trying to upload my Swagger JSON schema (myapi.json) into Atlassian Confluence using the swagger-confluence standalone tool.

The standalone CLI .jar should (according to my understanding) operate like this (used this page for credentials Base64 encoding):

java -jar <system path root>/swagger-confluence-cli-all-2.2-RELEASE.jar -u "http(s)://<server>:<port>/confluence/rest/api/" -b "<base64 encoded userid:password string" -a "<parent page id>" -k "<space key>" -g "true" -i "true" -s "<myschema.json>" -t "<Title for generated page>" -m "single"

Output (404 Not found):

2016-08-23 15:08:12.177  INFO - [main]  n.s.s.c.s.i.SwaggerToAsciiDocServiceImpl : AsciiDoc Conversion Complete!  
2016-08-23 15:08:12.178  INFO - [main] n.s.s.c.s.i.AsciiDocToXHtmlServiceImpl   : Converting AsciiDoc to XHTML5...
io/console not supported; tty will not be manipulated   
2016-08-23 15:08:16.888  INFO - [main] n.s.s.c.s.i.AsciiDocToXHtmlServiceImpl   : XHTML5 Conversion Complete!   
2016-08-23 15:08:17.728  INFO - [main] n.s.s.c.s.i.XHtmlToConfluenceServiceImpl : Posting XHTML to Confluence...
Exception in thread "main" org.springframework.web.client.HttpClientErrorException: 404 Not Found

It's caused a bit of confusion while searching for Confluence REST API examples, e.g. in Stackoverflow, as the API seems to have been changing some. However, Confluence REST API page suggests the current API should have been the same since Confluence Server 5.5. This is also described as a requirement in the swagger-confluence overview page.

The same requirements mention "A Confluence User with access to the REST API". How is this determined? I'm using an admin user. I found the general "Enable Remote API" configuration (which seemed to be enabled as default) under General Configuration -> Further Configuration as described in this article. The same article says the XML-RPC and SOAP APIs this setting enables are deprecated on Confluence 5.5+. Is the REST API enabled by default and is there a means to control the usage?

Also getting a bit weird results when trying to call the REST API (although I do get responses so that leads me to think the URL is correct).

curl -v -u userid:pass http://<server>:<port>/confluence/rest/api/  
...  
HTTP/1.1 302 Found  
...

But calling the URL http://<server>:<port>/confluence/rest/api/ with REST Easy (Firefox Plugin) with GET and providing userid & pass as Basic Authentication returns 200 OK HTTP status and seems to return my Confluence Dashboard (parent of the spaces; top-level page). Same also happens when accessing the URL with just browser.

Also numerous other attempts at calling the Confluence REST API with documented ways resulted in 404. Starting to think this is an authorization issue.. What am I doing wrong? Or is there a another way to produce results similar to Swagger Confluence demo?

Answer 1

Well, turns out even though http://<server>:<port>/confluence/rest/api/ returned HTTP 200 OK, the URL was wrong. The above is the so called "URL with context" (the /confluence/ part) and what I needed was the URL without context (no /confluence/ in the URL).

Here's how I tested the URL working by receiving the 200, Headers (-v) and page content as JSON response: curl -v -u user:pass http://<server>:<port>/rest/api/content/{id}
The page ID can be checked by pressing (or mouse-overing) the "Edit" button on the Confluence page.

And here's how I finally got the automatic Confluence upload working:
java -jar <system path root>/swagger-confluence-cli-all-2.2-RELEASE.jar -u "http(s)://<server>:<port>/rest/api/" -b "<base64 encoded userid:password string>" -a "<parent page id>" -k "<space key>" -g "true" -i "true" -s "<myschema.json>" -t "<Title for generated page>" -m "single"

The Swagger Confluence tool is awesome, by the way, and the results are as good as in the demo!

[Edited to add]:
Confirmed the Swagger Confluence library/tool (v2.2) to work on both my target Confluence Servers, versions 5.8.14 and 5.9.2