如何以编程方式将 Swagger API 文档发布到 Atlassian Confluence？ （使用 Swagger Confluence 工具和 Confluence REST API）

Question

我正在尝试使用 swagger-confluence 独立 tool 将我的 Swagger JSON 架构 (myapi.json) 上传到 Atlassian Confluence。

独立的 CLI .jar should（根据我的理解）这样操作（使用 this 页面作为凭据 Base64 编码）：

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"

输出（404 未找到）：

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

在搜索 Confluence REST API 示例时引起了一些混乱，例如在 Stackoverflow 中，因为 API 似乎已经改变了一些。然而，Confluence REST API page 建议当前的 API 自 Confluence Server 5.5 以来应该是相同的。这在 swagger-confluence 概述 page 中也被描述为要求。

同样的要求提到了“可以访问 REST API 的 Confluence 用户”。这是如何确定的？我正在使用管理员用户。我在通用配置 -> 进一步配置下找到了通用的“启用远程 API”配置（似乎默认启用），如article 中所述。同一篇文章说，此设置启用的 XML-RPC 和 SOAP API 在 Confluence 5.5+ 上已弃用。 REST API 是否默认启用，是否有控制使用的方法？

在尝试调用 REST API 时也会得到一些奇怪的结果（尽管我确实得到了响应，因此我认为 URL 是正确的）。

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

但是使用带有 GET 的 REST Easy（Firefox 插件）调用 URL http://<server>:<port>/confluence/rest/api/ 并提供 userid 和 pass 作为基本身份验证返回 200 OK HTTP 状态，并且似乎返回了我的 Confluence 仪表板（空间的父级；顶级页面） .仅使用浏览器访问 URL 时也会发生同样的情况。

还有许多其他尝试以记录方式调用 Confluence REST API 导致 404。开始认为这是一个授权问题。我做错了什么？或者有没有其他方法可以产生类似于 Swagger Confluence demo 的结果？

Answer 1

好吧，即使http://<server>:<port>/confluence/rest/api/ 返回 HTTP 200 OK，URL 错误。 以上就是所谓的“带上下文的 URL”（/confluence/ 部分），而我需要的是没有上下文的 URL（URL 中没有 /confluence/）。

以下是我通过接收 200、标头 (-v) 和页面内容作为 JSON 响应来测试 URL 工作的方法： curl -v -u user:pass http://<server>:<port>/rest/api/content/{id}
可以通过按下（或鼠标悬停）Confluence 页面上的“编辑”按钮来检查页面 ID。

这就是我最终让 Confluence 自动上传工作的方法：
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"

顺便说一句，Swagger Confluence tool 很棒，结果和 demo 一样好！

[编辑添加]：
确认 Swagger Confluence 库/工具 (v2.2) 可以在我的目标 Confluence 服务器版本 5.8.14 和 5.9.2 上运行