apidom-reference: OpenAPI 3.1 normalization

[char0n]

swagger-client has concept of normalization. This concept needs to be ported in ApiDOM as well. The goal of this issue is to research the process of normalization, understand it and implement it on ApiDOM side.

Research notes:

• normalization in swagger-client is performed on already dereferenced definition.
• can be skipped using skipNormalization option
• current normalization is mostly built to support OpenAPI 2.0 (only partial support for 3.0.x)
• decorates OpenAPI definition with $$normalized: boolean field and skips the normalization process if it detects that the field is truthy
• add normalized operationIds for Operation Objects that does have them
• correct Link.operationId references after the operationId normalization
• when normalizing operationIds v2OperationIdCompatibilityMode needs to be supported
• Parameter Objects are inherited from PathItem.parameters to Operation.parameters field. The rules of inheritance are defined here
• Security Requirements Objects are inherited from OpenAPI.security to Operation.security field. The rules of inheritance are defined here and here
• Server Objects are inherited in following sequence -> OpenAPI.servers -> PathItem.servers -> Operation.servers
• Parameter.example|examples normalization
• Header.example | examples normalization

[char0n]

In swagger-client integration we ideally want to use opId function from swagger-client. Function needs to be adapted in order to work. Here is a adaptation recipe:

const apiDOM = await parse(yamlDefinition);
const openApiElement = OpenApi3_1Element.refract(apiDOM.result, {
  plugins: [
    refractorPluginNormalizeOperationIds({
      operationIdNormalizer: (operationId, path, method) => {
        return opId({ operationId }, path, method, { v2OperationIdCompatibilityMode });
      },
    }),
  ],
});

[char0n]

Closing this issue as it has been addressed by multiple PRs and number of normalization refractor plugins have been introduced.