feat(converter): add securitySchemeTypeRefractorPlugin

[kowalczyk-krzysztof]

refs: SWG-9963

[kowalczyk-krzysztof]

As we discussed, the strategy is going to be different so I'm converting this PR to draft as I'm applying those changes.

[kowalczyk-krzysztof]

@char0n I updated the solution but I'm not sure if I'm handling it correctly (checking for name match). Could use some more feedback.

[char0n]

We now have working OpenApi3_1Element visitor hook. I'm now looking at ComponentsElement hook.

[kowalczyk-krzysztof]

@char0n Two things I'm unsure about:

1. When exactly should I push annotations? Is the current implementation too much?
2. As it is, the mutated SecurityRequirements looks like the code below - there is an empty object left. Should something be done about it?

"security": [
          {},
          {
            "apiKey-scheme": [
              "read",
              "write"
            ]
          }
        ],

[char0n]

1. When exactly should I push annotations? Is the current implementation too much?

Good question. Let me think about this for a minute.

2. As it is, the mutated SecurityRequirements looks like the code below - there is an empty object left. Should something be done about it?

"security": [
          {},
          {
            "apiKey-scheme": [
              "read",
              "write"
            ]
          }
        ],

We don't care. Empty Security Requirement Object is valid as empty object according to OpenAPI 3.0.x spec.

[char0n]

When exactly should I push annotations? Is the current implementation too much?

I guess this is dependent on the broader strategy how annotations should be generated. Do we want to generate annotation for every removed Schema Element or just generate one for the entire plugin?

I currently see two possible strategies for this. Let's stay in the realm of Security Scheme Object and model the strategies to that usecase.

Generate single annotation for plugin run

We'll just introduce semaphore variable into the plugin and in post we'll add the annotation if semaphore is set to true. semaphore is set to true whenever the Security Scheme Object is removed from the definition.

Another option is to add annotation when first Security Scheme Object is removed and guard that it's not added later again. This has advantage over the above post solution in retaining the real order of annotations as they are added right when they are generated.

Generate annotations for every element

Now this one would be more complex. We add annotation for every removal. Along with that we will translate element source maps to the annotation. This means that this single plugin can generate number of annotations and each annotation will contain specific source map information about the removed Security Scheme Object.

[kowalczyk-krzysztof]

When exactly should I push annotations? Is the current implementation too much?

I guess this is dependent on the broader strategy how annotations should be generated. Do we want to generate annotation for every removed Schema Element or just generate one for the entire plugin?

I think users of the converter would prefer to see information about all changes to the API definition and where they happened. So IMO Generate annotations for every element would work best.

[char0n]

I think users of the converter would prefer to see information about all changes to the API definition and where they happened. So IMO Generate annotations for every element would work best.

All right, decided then.

[char0n]

LGTM