Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Disambiguate AWS paths with fragment parameters #11
This fixes #2.
This PR is pretty complicated and does a few things:
It's in separate commits, which should help with reviewing!
Right now, all ambiguous paths are named with
This PR changes this so that every path includes a fragment that specifies the required parameters of an operation, which can be used to match it when the path is ambiguous. For example,
Fragment parameters may be query parameters, or header parameters. The names match the name of the parameter in the corresponding operation, regardless of location.
In some specs, near-identical endpoints are defined repeatedly, for the current & deprecated versions of the same operation. In that case, we add a
Some example paths from the generated S3 spec:
This isn't enough. The current implementation doesn't actually create parameters for most parameters in the AWS data, so we can't easily tell whether a given parameter in a fragment is a header or query parameter, or anything else about it.
Instead, right now every operation with parameters is given a single 'body' parameter, which includes every other specified parameter. For 'json' protocol services that's broadly correct, but it's not correct for any others, which are the vast majority.
This PR implements most of the per-protocol logic to define more-or-less correct parameters for each operation. This makes fragment routing possible, gives us better parameter data (including param descriptions etc), and makes the specs much more accurate.
This is close, but doesn't work 100%. For all primitive typed params, I believe it's correct. For object & array params, it simplifies things drastically. Nested object parameters are definitely not included, and I suspect others aren't quite right. Nonetheless, it's much closer than the current state. To take this further, I think we'd want to go to OpenAPI 3 (so we can use full JSON schema for params), and refactor the overall structure a fair bit (in short: I'd build the tree top-down, rather than trying to change it in place as in transformShape, which is super hard as it misses a lot of necessary context at each step).
A params comparison, to make this clearer:
Should be easy to run and check the diff locally, but to save time here's a couple of examples: