将多个Swagger API文档整合到一个“事实来源”文档中,以使开发人员能够更方便地利用API。
服务开发人员普遍存在一个问题,尤其是在微服务环境中,该问题可以描述如下。
The Problem
“陈述明确的问题是解决了一半的问题”-查尔斯·凯特林
想象一下,一组软件工程师正在开发一组微服务。 从最终用户的角度来看,前端开发人员正忙于照顾美观和可用性,他们需要知道如何将应用程序与API连接起来才能满足他们的需求,从而满足最终用户的需求。 , 要求。
如果我有多个微服务并且希望将端点记录在一个地方怎么办? 例如,为方便前端开发人员。 在这种情况下,第三方文档实现是Swagger UI。 在文献回顾期间发现的解决该问题的大多数尝试都取决于swagger-ui.html主页上下拉菜单的Swagger-UI提供的功能。 该解决方案意味着用户需要手动访问每个草签文档才能找到合适的服务。
Fig. 1.1 That label ‘Consolidated’, defaults to ‘Default’; it has been changed inside the source code. It is this dropdown that is used to control which of the APIs to view documentation for, in other solutions for this problem.
Literature Review
在本节中,“ Google认证的Google”也许是更准确的标题,因此,在期望得到控制的情况下,我将继续进行。
如前所述,过去尝试解决此问题的方法是使用Swagger UI的主页右上方的下拉菜单功能,如上图所示,用于选择API,以查看其文档 。
Here is an example that sees a Eureka server being used to discover each service to be documented. Eureka is a service discovery tool; further information pertaining to Eureka servers can be found here. Although elegant, it was felt that it was overkill to have a Eureka instance, solely for this purpose, and a consumer would lack a holistic view of all the services at their disposal.
Ťhis is another example that, although is without a third-party service discovery implementation, leaves us with the necessity to manually select and investigate, each end-point individually.
在此解决方案中,开发人员无需使用第三方服务发现工具,而只需配置所需的端点即可。 这是我想到的一个选择,这使我有信心继续我的打算。
A Solution
“解决方案通常比难题更漂亮。” –理查德·道金斯
该解决方案是一个Spring-boot应用程序,它同时还使用Springfox,可整合所有已配置的端点(内部application.yml)放入一个单一的草签文档中。 配置相对简单:
endpoints: # a list of sample base urls, note, omit "/v2/api-docs"
- name: UnusedName_key
url: https://api_server1.eon.de
username: joe_bloggs
password: joe_bloggs_pa55w0rd!
- name: UnusedName2_key
url: https://api_server2.eon.de
username: joe_bloggs2
password: joe_bloggs2_pa55w0rd!