feat: adds reusable actions to the components

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

Author: baywet

versions/1.2.0-dev.md

@@ -84,7 +84,7 @@ This is the root object of the [Overlay](#overlay).
 | <a name="overlay-version"></a>overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. |
 | <a name="overlay-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. |
 | <a name="overlay-extends"></a>extends | `string` | URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to. |
-| <a name="overlay-actions"></a>actions | [[Action Object](#action-object) or [Action Template Reference Object](#action-template-reference-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
+| <a name="overlay-actions"></a>actions | [[Action Object](#action-object) or [Action Template Reference Object](#action-template-reference-object) or [Action Reference Object](#action-reference-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
 | <a name="overlay-components"></a>components | [Component Object](#component-object) | A set of components to reuse across the Overlay Document. Optional. |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -138,6 +138,9 @@ The object provides a set of components to be reused across the Overlay document
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
 | <a name="component-action-templates"></a>actionTemplates | Map(`string`, [Action Template Object](#action-template-object)) | A key-value set of action templates to reference in the actions. Optional. |
+| <a name="component-actions"></a>actions | Map(`string`, [Action Object](#action-object) or [Action Template Reference Object](#action-template-reference-object)) | A key-value set of actions or action template references to use in the actions. Optional. |
+
+> Note: the target field for components actions is Optional.
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -195,6 +198,15 @@ This object MAY be extended with [Specification Extensions](#specification-exten
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
+#### Action reference object
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="action-reference-ref"></a>$ref | `string` | **REQUIRED** A valid reference to an action in the components section, represented as `#/components/actions/actionTemplateKey`. |
+| <a name="action-reference-target"></a>target | `string` | A RFC9535 JSONPath query expression selecting nodes in the target document and overrides the target defined in the referenced action. Optional when the resolved action defines a target, required when the resolved action does not. |
+
 #### Action template reference object
 
 ##### Fixed fields
@@ -635,6 +647,91 @@ paths:
           description: OK
 ```
 
+##### Action Reference Example
+
+###### Source Description
+
+```yaml
+openapi: 3.2.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: OK
+  /some-items:
+    delete:
+      responses:
+        200:
+          description: OK
+```
+
+###### Overlay
+
+```yaml
+overlay: 1.2.0
+info:
+  title: Use templates to insert error responses
+  version: 1.0.0
+components:
+  actions:
+    errorResponse:
+      update:
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  type: string
+      description: Adds an error response to the %param.pathItem% path item %param.operation% operation
+actions:
+- $ref: '#/components/actions/errorResponse'
+  target: "$.paths['items'].get.responses"
+- $ref: '#/components/actions/errorResponse'
+  target: "$.paths['some-items'].delete.responses"
+```
+
+###### Result description
+
+```yaml
+openapi: 3.2.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: OK
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+                properties:
+                  errorMessage:
+                    type: string
+  /some-items:
+    delete:
+      responses:
+        200:
+          description: OK
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+                properties:
+                  deleteErrorMessage:
+                    type: string
+```
+
 ##### Action Template Example
 
 ###### Source Description