Ever thought about a feature to require explicit annotations to include a parameter in a code snippet

[michaelgwelch]

Hi @ErikWittern I'm maintaining a fork of this great library with some changes we've made.

One additional change I'm considering is to require some explicit "signal" to include a parameter in a code snippet.

The current default behavior can lead to non-sensical snippets or unnecessarily complicated snippets. For example, you may have mutually exclusive parameters. Or you may have headers that are seldom used show up in a snippet. For various reasons I want to control which parameters make it into the snippet.

Had you ever considered this feature when working on your library? I have an idea, but want to be careful of invalidating all existing test cases. So maybe I'll make it a config setting to enable this new mode. Once the mode is enabled I think it'll require vendor extensions on parameters or operations to signal which parameters are desired and which value.

[ErikWittern]

Hi @michaelgwelch, thanks for inquiring!

First off, I know am very inactive w.r.t. this repository. I wrote this code at a time when I was researching APIs at IBM Research. I have since changed jobs and no longer have much need or professional incentives for spending a lot of time maintaining this library, unfortunately.

I have not considered adding more fine-granular controls over parameters or headers. My intuition would be to, by default, include all the information present in a given OpenAPI document, and allow to explicitly exclude them from being included in a generated snippet. One way to do so is to add optional configuration parameters, which allow to "block-list" certain things. Another, likely more extensible and generic, way to exclude certain pieces of information is of course altering the OpenAPI document itself, before passing it to openapi-snippet. I am currently uncertain whether there could be a benefit from openapi-snippet providing a "preprocessing hook" for that purpose.

If time would permit, I would likely want to rewrite the library in TypeScript, ensure compatibility with both CJS and ESM, and make sure it keeps in sync with the latest version of OpenAPI.

[michaelgwelch]

Since our fork is now being tailored to our needs I ended up doing this: https://github.com/jci-metasys/openapi-snippet?tab=readme-ov-file#parameter-examples