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.