[swagger-codegen] Generating single client for multiple API definitions

[chamindias]

Description

When we use swagger codegen to generate client side SDKs, we are able to generate one SDK per API definition (for a given language). Please refer the example below.

Eg : If we have 2 APIs, say "GeoAPI" and "TimeAPI", we need to generate 2 SDKs (i.e - 2 separate jar files) with the existing implementation, since the library supports only one definition at a time.

Limitation here is, if someone needs to consume both "GeoAPI" and "TimeAPI", he needs to write 2 separate clients.

If a user can get a single jar file and include it in his project, he can use a single client to consume both "GeoAPI" and "TimeAPI". For that, we need to have root pom.xml file which builds the individual SDKs. (This root pom.xml should be created automatically by the library at the time of SDK generation.) In other words we need to generate one client from multiple swagger definitions.

Please let us know the possibility of this with the current implementation of swagger codegen.

Swagger-codegen version

2.2.0

[cbornet]

I think it's a good thing to use separate clients for distinct APIs:

• they have different authentication schemes and credentials
• they could have been generated with different swagger-codegen versions

[wing328]

In addition to what @cbornet has pointed out, some developers expressed concern about the size of the SDKs being too large before so breaking a giant SDK into smaller SDKs may be more preferable for those developers.

[fonix232]

This could come handy in certain scenarios.

For example, for modularity, one of our projects uses separate Swagger docs for each "module" (endpoint) of the API. This is so versioning can be independent on each endpoint, and also to be able to group the endpoints by function (e.g. a client may be using endpoints A, B, E and F, and a management web UI might only use A, C, D and F - they do not need the whole client library, and such, separate libraries are generated). But this means that since we have separate swagger configs for each endpoint (A, B, C, D, E and F in our sample), we need that many client libraries.

[kgilmer]

+1

Yes it's obvious that client-per-API by default is the best approach, but in support of @chamindias, there are also use-cases in which you would want to provide one client for a set of APIs. In addition to @fonix232 's comment about versioning, if you happen to have very granular APIs, it quickly becomes tedious to manage all these client JARs. Additionally, in Android, there is additional build-time complexity in managing conflicts in the generated code that is common across client libraries.

[chenrui333]

+1

I wonder if there is swagger-codegen function to traverse the api paths and generate all the client stubs.

[cbornet]

I understand the use case for grouping micro-services endpoints (eg. for an API Gateway). Personnally I would use an external tool to merge the specs so that I have a reference swagger for it but maybe some people would appreciate doing it directly from the codegen.

[kgilmer]

Hi @cbornet yes in my case it's due to segmenting our APIs across multiple API Gateways for tangental reasons. Are you aware of any specific tools that do this spec merging?

[cbornet]

There are a lot (just google "swagger merge", you'll see 😃). I haven't tested one in particular and it's also not hard to code your own if they don't fit your need.