Shared components between multiple OpenAPI documents

[hrabkin]

Question

How to union generated shared components from two different openapi specifications?

[czechboy0]

Hi @hrabkin, can you clarify what you mean by "union"?

You can generate content from two OpenAPI documents into two Swift modules, and if you add accessModifier: package (or public), you can then have a third Swift module that imports the first two, and uses types from both.

Are you writing a client or a server? Can you add more details on what you're trying to do?

[czechboy0]

I'm trying to understand whether this is essentially a duplicate of #132 or if that doesn't work for you for some reason.

[hrabkin]

No its not a duplicate. Its a different issue, that one not related.

So I have two apis described in openapi yaml: A -> which have some shared components S, and B which uses the same shared components S. I generate two libraries from the yamls and of course there are two duplicate types now AS and BS.

[simonjbeaumont]

So I have two apis described in openapi yaml: A -> which have some shared components S, and B which uses the same shared components S. I generate two libraries from the yamls and of course there are two duplicate types now AS and BS.

I'm not sure I understand.

If by "two apis" you mean you have two operations in the OpenAPI document that make use of the same type in #/components/schemas, then these will use the same type. Or are you saying you two independent services in the one YAML file?

Would you be able to provide a minimal example to help us understand better?

[Inshaki]

I’m facing a similar issue and would appreciate some guidance.

We have two separate JSON files, each defining the same "User" component. These components are currently in different modules but represent the same entity. I'm looking for a way to unify them, so I can use just one.

For example:

- Module Address:
public typealias User = Components.Schemas.User // from Address module OpenAPI file

- Module Car:
public typealias User = Components.Schemas.User // from Car module OpenAPI file

However, in my code, I can’t do the following:
func test(_user: Address.User) { var user: Car.User = _user // error }

[simonjbeaumont]

We have two separate JSON files, each defining the same "User" component. These components are currently in different modules but represent the same entity. I'm looking for a way to unify them, so I can use just one.

@Inshaki the types generated in different modules are distinct, and there's no way to unify them.

Can you confirm if these are separated into separate files because they are separate services or just because you want to spread the definition of your single API service across multiple files.

If it's the former, you'll need to restructure to separate the shared types into their own OpenAPI doc, generate in their own shared target, and use additionalImports: in the config file of the two downstream targets.

If it's the latter, then Swift OpenAPI Generator only supports a single openapi.yaml or openapi.json for each target and it's expected that this contain the entire API, so you could explore some preprocessing to merge this into one OpenAPI document that defines your service.

For example:

- Module Address: public typealias User = Components.Schemas.User // from Address module OpenAPI file

- Module Car: public typealias User = Components.Schemas.User // from Car module OpenAPI file

However, in my code, I can’t do the following: func test(_user: Address.User) { var user: Car.User = _user // error }

I can't really tell which of these it is from this example. Do you have a CarAPI and an AddressAPI (probably not), or do you have a single API that makes use of cars and addresses, that both have users?

(Just a logistical note here that I'm about to head out for a long weekend so you might not hear from me until Tuesday).

[Inshaki]

The CarModule and AddressModule are indeed separate modules (within the same backend though), each with its own set of APIs. However, they share some common models like User. While creating a shared OpenAPI document seems like a solid approach, we prefer not to modify the existing JSON files directly.

Given this, would it be possible to set up the shared components without altering the original JSON files? If so, how would you recommend structuring this?

Any further guidance would be greatly appreciated.

[simonjbeaumont]

If the set of OpenAPI document JSON files you have to hand constitute the API definition of a single backend, then you will need to preprocess them as input to Swift OpenAPI Generator since it only supports a single OpenAPI document as input, named either openapi.yaml or openapi.json.

You will likely need to use another tool for this as part of your build pipeline, e.g. jq.

[czechboy0]

I suspect this would also be helped by #25, as it'd allow actually generating a single copy of the shared types, and they'd be referenced from both modules.

[hactar]

Ran into this limitation now too: I've been tasked to write a proxy server that takes a search term, queries 3 other APIs for that search term, filters and merges the results and returns them. All APIs, including the server I'm writing, return a GeoJSON FeatureCollection (https://datatracker.ietf.org/doc/html/rfc7946) which I've added to my OpenAPI Scheme.

So I have 4 targets: 3 openapi clients, 1 openapi server. Each target has its own openapi file because unfortunately every server has a slightly different query syntax. All of the clients return a Components.Schemas.FeatureCollection, and the server will return a Components.Schemas.FeatureCollection too. But obviously each Components.Schemas.FeatureCollection is actually something different for the compiler: ClientOne.Components.Schemas.FeatureCollection, ClientTwo.Components.Schemas.FeatureCollection, ClientThree.Components.Schemas.FeatureCollection and ServerAPI.Components.Schemas.FeatureCollection - so I can't nicely pass them around and work with them without "converting" them first.

Only workaround at the moment I can think of is to "mangle" all four openapi specs into one spec, have only one module, and generate both client and server there - but the resulting openapi file wouldn't be clean and "truthful": nothing would prevent my from calling ClientOne's search api on ClientTwo, and my Server API would have 3 "empty" implementations for the server stubs of the APIs I'm calling, not providing.

Adding this as a reference to a "further" usage scenario to hopefully cover once this is worked on.

[czechboy0]

I think keeping the modules separate is the most accurate representation of reality (in theory one of the 4 could change without the other 3, and get out of sync).

I'd recommend hand-writing this shared type as a struct in your server module, and write an initializer on this type from each of the 3 client variants, and write an initializer on the server variant that takes this hand-written variant.

That way you can keep business logic types separate from API types, which I would recommend anyway (for testability, for example).

It's also true that external references could help here, as long as you could enforce that all 4 APIs always use the same shared type and get deployed together.