用于多个RESTFul服务的Swagger UI

Question

我在这里阅读了以下内容：

Swagger 目前没有从客户端或服务器的角度包含支持多个 API 版本的建议 — 声明了版本控制信息（规范和底层 API 实现）。

我想知道的是如何配置swagger UI以显示多个服务的API，即驻留在不同服务器上的服务。我尝试在不同的服务器上配置swagger UI，但出现以下错误：

无法从服务器读取。它可能没有适当的访问控制源设置。

我读过关于在服务器上启用CORS的文章，但这对我没有帮助，因为服务是在liberty profile上运行的。

Swagger UI配置在WAS的本地运行liberty配置文件上，而服务运行在不同的WAS实例上。

我的方向是为多个服务提供UI，但我认为这是一个合乎逻辑的起点。

Answer 1

我们在各种行业级API中看到的是，该版本直接进入路径，其中v1是可选的。

因此，如果您将“/path/resource”作为V1，那么您可以将“/v2/path/resource”作为V2，并且两者可以在所有版本的Swagger中愉快地共存。

您提到您使用的是WebSphere Liberty，因此这里还有两点可能会帮助您：

>

从 2016 年 1 月的 Beta 版开始，WebSphere Liberty 原生支持 CORS。您只需使用所需的 CORS 选项配置服务器.xml。文档在这里： https://www.ibm.com/support/knowledgecenter/was_beta_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_webcontainer_cors_config.html

domain 属性适用于您希望应用此配置的应用程序根目录，这意味着它不会影响任何其他上下文根目录。其他7个属性完全遵循官方CORS规范（https://www.w3.org/TR/cors/），因此它们非常不言自明。

测试版链接：https://developer.ibm.com/wasdev/downloads/liberty-profile-beta/

由于您使用的是Swagger和Liberty，因此您应该查看Liberty的新API Discovery：https://developer.ibm.com/wasdev/blog/2016/02/17/exposing-liberty-rest-apis-swagger/

基本上，在server.xml中打开apiDiscovery-1.0，服务器将自动处理Jaxrs (1.1或2.0)注释、Swagger注释和预生成的文档(META-INF/swagger.json或META-INF/swagger.yaml)。然后，您将能够看到来自/ibm/api/docs的聚合文档和来自/ibm/api/explorer的UI。

Answer 2

看看DynamicApis.com.

这是一个新的API门户平台，在这方面做得很好。他们拿走你的大摇大摆的JSON，然后用它来构建你的API门户。它们还集成了本机REST API，您可以自动将API同步到门户。

下面是一个示例门户，他们展示了如何承载多个API。

下面是他们的文档外观的示例。它就像炫耀一样，但完成了并占据了一个档次。

Answer 3

似乎Swagger 2规格很快就会允许这样做。看看这个似乎是贡献者的人的回应：

我们目前正在最终确定将多个微服务整理成单个集合的能力，但最终，每个微服务仍将是单个文件。

https://stackoverflow.com/a/26917653/3389881

斯威格谷歌集团中的同一个人评论：https://groups.google.com/forum/#!主题/swagger-swaggersocket/H7dsSd6VPvM

这个人找到了一种方法，将多个Swagger 2定义组合在同一个地方:http://utility-stack.apievangelist.com/index.html

最后，Swagger 1似乎支持多个API基本路径。