search

vrchatapi / specification

⚙️ VRChat API OpenAPI specification defining the API in a machine-readable format. This is then used for automatic generation of language-specific SDK's
MIT License
49 stars 30 forks source link

Redocly Decorator: x-feature #371

Open 0xkubectl opened 3 months ago

0xkubectl commented 3 months ago

POC for https://github.com/vrchatapi/specification/issues/370

This is a draft and not done. Its more to see if the idea works and to gague how other contributers like the impl.

Things missing:

Not sure if there is the right place to put this plugin. Feedback is welcome :3

ariesclark commented 3 months ago

Is there any particular reason behind changing the structure of the proposal? And I'm not sure where available_features comes from. Is this code functional?

0xkubectl commented 3 months ago

The code is functional, if you have a look here, you can see that available_features is a configuration value. The idea being that this decorator can deal with more that one feature at a time. I.e. there are 3 Features of OpenAPI requried to accurately describe an Api. As some generators only support a different subset of those features, you can run redocly with different config values and produce specs that satisfy the feature constraints of a given generator.

If I understood you proposal correctly the decorator would only have supported one feature (either use the fallback or dont), which would limit the use of other operators like anyOf or allOf. On why I changed the exact syntax, I wanted it to be clear what is replaced and how. If all required features are present x-feature will be rendered what is in the desired object and otherwise whats in the fallback object. Futhermore I believe this allows for more flexibility as instead of just one key, a whole object with multiple properties can be added or removed, based on features.