Resolve remote schemas #602
Conversation
Codecov Report
@@ Coverage Diff @@
## main #602 +/- ##
==========================================
+ Coverage 88.53% 93.52% +4.99%
==========================================
Files 9 11 +2
Lines 349 510 +161
Branches 123 183 +60
==========================================
+ Hits 309 477 +168
+ Misses 37 32 -5
+ Partials 3 1 -2
Continue to review full report at Codecov.
|
| export interface operations {} | ||
|
|
||
| export interface external { | ||
| "https://raw.githubusercontent.com/drwpow/openapi-typescript/main/tests/v3/specs/petstore.yaml": { |
There was a problem hiding this comment.
This is the basic format of loading remote schemas:
export interface external {
[namespace]: {
// … subschema
}
}Looking at how json-schema-ref works, it does a really good job of flattening schemas. But since we’re converting to TypeScript, I have some hesitations in trying to flatten and convert to a different language.
While keeping every subschema within is own namespace is verbose, it’s not limiting. So I feel it meets one of the project goals: support any valid OpenAPI schema, no matter how complicated. The big area of concern is conflicts: just because you reference User in a remote schema, doesn’t mean that you want the rest of that remote schema’s definitions to be flattened and possibly conflict with your own. To prevent that, this approach of namespacing everything lets you reference foreign components in every direction without trying to merge objects that may not be intended or even capable of merging.
If this approach disagrees with the spec (e.g. if the spec demands that all names be unique even across remote schemas) I’d be happy to revise it, but I had trouble finding a clear answer on that. To me it seems illogical that a schema would either be valid or invalid based on remote refs, and so the external interface was born, and this syntax.
| /** this is a duplicate of spec.yml#components/schemas/Remote1 */ | ||
| Remote1: string; | ||
| Remote2: external["subschema/remote2.yml"]["components"]["schemas"]["Remote2"]; | ||
| Circular: components["schemas"]["Circular"]; |
There was a problem hiding this comment.
If you have a circular reference back to the original schema, that’s preserved! 🎉
drwpow
force-pushed
the
remote-schema
branch
3 times, most recently
from
c378e4f
to
4891ae7
Compare
|
Update: this will be merged and v4 will be cut after #616 is merged as the final release of v3 (for now). |
drwpow
force-pushed
the
remote-schema
branch
4 times, most recently
from
d2aa96f
to
200ae7f
Compare
|
Merged! We are now officially in |
Resolves #321 and adds support for:
The goal was pretty straightforward, but quite a bit of code had to change. The major change was moving the loader from the CLI into the Node API. Before, the Node API had to receive a JSON object. Now, the Node API can handle a string pointing to a local file or remote URL (README updated). There was a lot more prep work done, but that was merged in #612 to prepare for this PR (and make v3 much easier to patch, if needed).
This PR will act as a bit of an RFC to see if this is preferable before moving forward (see comments for generated schema).
Merging this will mean version 4.0! 🎉 It will disrupt Node.js API users by changing the main method from sync to async. Other than that, no other breaking changes, which means v4 will be backwards-compatible with v3 for all CLI users.
Before merging, I’d like to resolve #607 and #584 in v3. And this feature will be the first release of v4. So this PR will be merged as soon as those are resolved and published.Last outstanding item before merging: #616. This will follow that!