Nswag: [Question] Generate one client from several swagger specs/versions

[Boriszn]

Hi Rico,

I have small question.

Background.
I have several swagger api versions.
Like:

• http://localhost:5002/swagger/v1/swagger.json
• http://localhost:5002/swagger/v2/swagger.json

Question:
Is it possible to generate only one client from 2..n swagger openAPI specs / versions ? (Maybe NSwag has merge option etc?)

Thanks in advance.

[RicoSuter]

There is no prebuild feature which supports that... i recommend to build an own simple cli app based on nswag.core which merges multiplr specs into one...

[Boriszn]

Hi Rico, thanks a lot for the feedback.

I probably have to implement Open API merging logic/templates by myself. Or is it included in nswag.core ?

[RicoSuter]

No, it's not yet implemented, but it would be a great addition to nswag.core

[RicoSuter]

The hard part would be to merge dto schemes (i.e. remove redundant ones, etc.). I don't know if there is a way to do this generically (i.e. which works for everyone :-)

[Boriszn]

Hi Rico, sure I will try to help here.
So found how this was implemented in following components:

• swagger-cli
• swagger-merger
• swagger-combine

Have one question isn't this feature was implemented, here the closed issue 1326 ?

Please correct me if I wrong.

[RicoSuter]

@Boriszn this is different: It allows to add multiple specs to the ui, they are still separate from each other and actually not merged...

[ghgithub]

I have small question.

[PureKrome]

@Boriszn Heya! Did you ever have any luck with this? Surely this is a common feature -> multiple private microservices (with OpenApi swagger docs) behind a single API Gateway which is where the single doc, should exist?

@RicoSuter have you ever had to do this?

EDIT:

If 'yes', can you show some sample code, using those two sample microservice urls, above please?

[RicoSuter]

No, i didn't have the need to do this yet.

But in theory you'd download both specs, parse it with the OpenApiDocument class and then merge the two instances (this might be quite tricky if there are overlapping types, etc.)

[PureKrome]

Thanks @RicoSuter for the prompt reply - really appreciate it.

Since I posted that, I ended up stumbling across this project which is an NPM package (sadness) but actually works.

I've created a json file which lists my real life external swagger API's and ends up creating a single output yml file which I assume I could then use to generate a single SDK.

You were totally right about the "Overlapping Types, etc.". I initially had trouble with the merging because each separate swagger file had their own operationId ... but the same ones were generated in each other swagger. So when it came to merge/join, got failure errors.

so yeah, interesting! I've still got more work to do, to see if this all really works out ... but i was totally expecting this to be a common thing (1x schema for multiple api's).

[RicoSuter]

If you use nswag to generate the individual specs then the operation ids are controller_operation and if the controller names are unique over all projects then you should be fine.

[RicoSuter]

Another option would be to generate muliple files (for each api) into a single sdk project.

[PureKrome]

controller names are unique

they aren't :( Is there a way to specify a different naming convention for the operation ids?

for example:

• microservice 1 : microservice-1-<controller>-<operation>
• microservice 2 : microservice-2-<controller>-<operation>

Another option would be to generate muliple files (for each api) into a single sdk project.

Can you elaborate what you mean by this, please?

[Boriszn]

Hey @PureKrome

I've combined several swagger API specs with API gateways e.g Azure API Management, Ocelot. Also, I've have used swagger-combine (almost like swagger-combine) in the dev ops pipeline.

[joeyeng]

I tried out swagger-combine, but it de-references all object definitions so I'm not sure how it's useful as input for client generation. I think the best option is probably to consolidate multiple generated clients into one library as @RicoSuter suggested.

Otherwise, if a merger was implemented (in NSwag.Core) perhaps it can be strict about duplicate type names and ignore dupes if they've already been added to the client.