search

RicoSuter / NSwag

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.
http://NSwag.org
MIT License
6.69k stars 1.24k forks source link

[Question] Generate one client from several swagger specs/versions #1273

Open Boriszn opened 6 years ago

Boriszn commented 6 years ago

Hi Rico,

I have small question.

Background. I have several swagger api versions. Like:

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

RicoSuter commented 6 years ago

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 commented 6 years ago

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

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

Please correct me if I wrong.

RicoSuter commented 6 years ago

@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 commented 5 years ago

I have small question. image

PureKrome commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

PureKrome commented 4 years ago

controller names are unique

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

for example:

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 commented 4 years ago

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 commented 4 years ago

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.