Question: Best way to aggregate multiple Swagger endpoints in a single HTML page

[mbukosky]

Hi,

I was wondering if anyone had a best approach for joining multiple Swagger endpoints together in a single HTML page. I have been searching the tubes for a while but I haven't been able to find a great example that uses the newer 2.0 spec. Here are some ideas I was thinking about

1. Multiple SwaggerUI objects
2. Manually build a single SwaggerUI object that uses a Path Item Object and links to a different endpoint with $ref . Each endpoint would have its own path with a $ref. example
3. Use micro-services with the 1.2 spec. In this case, I would use the apis field on the SwaggerUI object. Does the 2.0 spec have an apis equivalent?
4. Something else???

Many thanks in advance

[solher]

+1

[fehguy]

Current swagger-ui won't have this support. There may be something in the future but for now, I'm going to close this out as out-of-scope.

[gtrias]

Hi,

I think this is a must-have for swagger-ui, I'm thinking about to use swagger to make my API documentation independent of the code/framework/technology/server because I'm writing microservices and I would like to have all them documented in the same place, all together. I already have NelmioApiDoc in some projects so since swagger-ui doesn't support multi-api it doesn't make any difference..

Thanks

[mbukosky]

@gtrias Not sure if it helps, but I was able to solve my problem by building a custom solution. I created a Single Page Application with Angular to swap in and out swagger docs from different services. I used a simple bootstrap tools for a nav pane. Overall, it turned out really well but I did run into issues with loading older versions of swagger-ui, but I was able to hack my way around them.

[webron]

FWIW, courtesy of @ponelat - https://gist.github.com/webron/7c41db7f777471fcbc10

[mbukosky]

@webron yeah that is basically what I did, but I wrapped that code into an angular directive so I could swap them in and out.

[gtrias]

Thank you @mbukosky and @webron I'll try to achieve this functionality that way. @mbukosky do you have your code released as open source?

[mbukosky]

@gtrias No, that code is currently internal, but I can bring it up during our next meeting to see if this is something we can release.

[varghgeorge]

Take a look at the demo application to view all service documentations at a single location: https://github.com/varghgeorge/microservices-single-swagger

[gtrias]

Thank you so much @varghgeorge!! I'll take a look right now. BTW I just found this other option:
https://github.com/thanhson1085/swagger-combined , I didn't tried it already but it seems to accomplish the same.

[varghgeorge]

@gtrias Thank you.

Thanks for the reference to swagger-combined. Both approaches address the same problem but in different ways.

swagger-combined seems to be creating one document by listing all service documentations on a single page.

single-swagger lists all available services in the top dropdown and let user can select a service to view the details of that service.

Good to have different options. :-)