Uplift OpenAPI v3.1.0

Issue #1610 - https://github.com/OAGi/Score/issues/1610

• OpenAPI v3.0.3 - Operation Object (https://spec.openapis.org/oas/v3.0.3#operation-object)

  • The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.

• OpenAPI v3.1.0 - Operation Object (https://spec.openapis.org/oas/v3.1.0#operation-object)

  • The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.

• Differences between v3.0.3 and v3.1.0

  • Data Types:

    • v3.0.3: Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution).

    • v3.1.0: Data types in the OAS are based on the types supported by the JSON Schema Specification Draft 2020-12. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part.

  • OpenAPI Object:

    • webhooks field has added in v3.1.0.

      • The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An example is available.

  • Info Object:

    • summary field has added in v3.1.0.

      • A short summary of the API.

  • License Object:

    • identifier field has added in v3.1.0.

      • An SPDX license expression for the API. The identifier field is mutually exclusive of the url field.

  • Components Object:

    • pathItems field has added in v3.1.0.

      • An object to hold reusable Path Item Object.

  • Operation Object:

    • responses field is not required anymore in v3.1.0.

  • Parameter Object:

    • schema field could be either Schema Object or Reference Object in v3.1.0, but it must be Schema Object in v3.1.0.

    • spaceDelimited and pipeDelimited style values allow for either separated array values or object values in v3.1.0.

  • Media Type Object:

    • schema field could be either Schema Object or Reference Object in v3.1.0, but it must be Schema Object in v3.1.0.

  • Encoding Object:

    • Descriptions for contentType, style, explode, and allowReserved fields have changed in v3.1.0.

  • Callback Object:

    • Reference Object is allowed for the expression of the field pattern in v3.1.0.

    • The webhooks field can be used to describe incoming requests from the API provider independent from another API call in v3.1.0.

  • Reference Object:

    • summary and description fields has added in v3.1.0.

  • Schema Object:

    • nullable, readOnly, writeOnly, and deprecated fields have removed in v3.1.0.

  • Security Scheme Object:

    • mutualTLS is valid for the type field in v3.1.0.

  • Security Requirement Object:

    • In v3.1.0, for other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band.