Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Shared components between multiple OpenAPI documents #564

Open
hrabkin opened this issue Apr 18, 2024 · 9 comments
Open

Shared components between multiple OpenAPI documents #564

hrabkin opened this issue Apr 18, 2024 · 9 comments
Labels
kind/support Adopter support requests. status/triage Collecting information required to triage the issue.
Milestone

Comments

@hrabkin
Copy link

hrabkin commented Apr 18, 2024

Question

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

@hrabkin hrabkin added kind/support Adopter support requests. status/triage Collecting information required to triage the issue. labels Apr 18, 2024
@czechboy0
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Author

hrabkin commented Apr 18, 2024

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
Copy link
Collaborator

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
Copy link

Inshaki commented Aug 23, 2024

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
Copy link
Collaborator

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
Copy link

Inshaki commented Aug 27, 2024

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
Copy link
Collaborator

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
Copy link
Contributor

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.

@czechboy0 czechboy0 changed the title OpenAPI shared components Shared components between multiple OpenAPI documents Oct 29, 2024
@czechboy0 czechboy0 added this to the Post-1.0 milestone Oct 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind/support Adopter support requests. status/triage Collecting information required to triage the issue.
Projects
None yet
Development

No branches or pull requests

4 participants