feat: limit the generated names of the $refs #47
Conversation
If we use a generator to produce a Ruby client, and then try to build that gem, it's possible for the RubyGems build process to fail with: `ERROR: While executing gem ... (Gem::Package::TooLongFileName)` This can happen if the $ref ids we are using are too long. This PR makes 3 changes which are applied during the generation of ids only if they too long: - error responses that can be "one of" many, will now no longer use all of the error names to generate the id - nested partial responses will no longer use all of the parent field names in the id generation - endpoint ids will resort to using the initials of the full path, when the id has a clash and the path is too long (this will be super rare). this is a breaking change, but we're on 0.1.1 and not actually using any generated clients yet. So I'm not marking it as such. closes: #46
|
@jimeh I went ahead and merged this without your review because I didn't want block anyone from trying out the generated clients. Also I figured it's better to get something published than have nothing. Given no-one is using this yet, I figure we can be quite bold at this point. If you hate what i've done, then we can easily revisit. If we continue to have problems with the length of $ref ids and corresponding filenames that are generated. Then a more involved solution could be adapt Apia so that some kind of "short id" could be defined on the endpoint itself in the app that defines the actual API. Then our schema generator could use this "short id", instead of relying on the path of the endpoint. This would give the user the control to apply acronyms or simply leave out words as appropriate. I don't think we could make this "short id" mandatory, so either way I think we'd need this automatic shortening logic (or some version of it, that i've implemented in this PR). It's also worth pointing out that declaring a "short id" for an endpoint wouldn't make any difference for the way we need to name error responses, so it wouldn't solve everything anyway. |
|
@paulsturgess that all sounds reasonable to me. I've only had a very brief look at the code changes, but what you've described sounds good to me. It'll be nice to get all this stuff off the ground :) And if you want, I'm happy to have a deeper dive with you into this next week when I'm back. |
If we use a generator to produce a Ruby client, and then try to build that gem, it's possible for the RubyGems build process to fail with:
ERROR: While executing gem ... (Gem::Package::TooLongFileName)This can happen if the $ref ids we are using are too long.This PR makes 3 changes which are applied during the generation of ids only if they too long:
this is a breaking change, but we're on 0.1.1 and not actually using any generated clients yet. So I'm not marking it as such.
closes: #46