CODEWITHSUNDEEP
swaggerswagger-ui
Aspirant
Aspirant

Reputation: 1954

Swagger UI for multiple RESTFul services

I read the following here:

Swagger does not currently include a suggestion for supporting multiple API versions from a client or server point of view—versioning information (both of the spec and the underlying API implementation) are declared.

What I wish to know is that how to configure swagger UI to show the API for multiple services, i.e. services residing on different servers. I tried working with configuring the swagger UI on a different server but I get the following error:

Can't read from server. It may not have the appropriate access-control-origin settings.

I have read about enabling CORS on the server but that did not help in my case as the services run on liberty profile.

Swagger UI is configured on a locally running liberty profile of WAS and the services run on a different WAS instance.

The direction I am moving is to have UI for multiple services, but this I thought is a logical starting point.

Upvotes: 3

Views: 9869

Answers (3)

ArthurDM
ArthurDM

Reputation: 403

What we have seen in various industry-level APIs is that the version goes right into the path, where v1 is optional.

So if you have "/path/resource" as your V1, then you could have "/v2/path/resource" as your V2, and both can happily co-exist in all versions of Swagger.

You mentioned you're using WebSphere Liberty, so here are two additional points that might help you out:

  1. Starting with the January 2016 Beta, WebSphere Liberty supports CORS natively. You just configure the server.xml with the CORS options you want. Docs are here: https://www.ibm.com/support/knowledgecenter/was_beta_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_webcontainer_cors_config.html

    The domain attribute is for the application root that you want this configuration to apply to, which means it won't affect any other context roots. The other 7 attributes follow exactly the official CORS spec (https://www.w3.org/TR/cors/), so they are pretty self explanatory.

    Link to beta: https://developer.ibm.com/wasdev/downloads/liberty-profile-beta/

  2. Since you're using Swagger and Liberty, you should check out the new API Discovery from Liberty: https://developer.ibm.com/wasdev/blog/2016/02/17/exposing-liberty-rest-apis-swagger/

    Basically, you turn on apiDiscovery-1.0 in your server.xml and the server will automatically process your Jaxrs (1.1 or 2.0) annotations, Swagger annotations, and pre-generated docs (META-INF/swagger.json or META-INF/swagger.yaml). You will then be able to see the aggregated doc from /ibm/api/docs and the UI from /ibm/api/explorer.

Upvotes: 0

Jerrod Horton
Jerrod Horton

Reputation: 1692

Check out DynamicApis.com.

It is a new API portal platform that does a great job with this. They take your Swagger JSON and build your API portal out of it. They also have native REST API integration where you can automatically sync up your API to your portal as well.

Here is an example portal they have up to demonstrate how multiple APIs can be hosted.

Here is an example of what their documentation looks like. It is like swagger but done up and taken up a notch.

Upvotes: 0

carlisia
carlisia

Reputation: 121

It seems that Swagger 2 specs will allow this soon. Look at this response from someone who seems to be a contributor:

We're currently in the process of finalizing the ability to collate several micro-services into a single collection, but eventually, each micro-service is still going to be a single file.

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

Same person comments in the Swagger Google group: https://groups.google.com/forum/#!topic/swagger-swaggersocket/H7dsSd6VPvM

This person has found a way to group multiple Swagger 2 definitions in the same place: http://utility-stack.apievangelist.com/index.html

Finally, it seems that Swagger 1 would support multiple API basepaths.

Upvotes: 5

Related Questions