Docs: Add examples for the filter decorators

docs/decorators/filter-in.md

@@ -4,7 +4,7 @@ Preserves nodes that have specific `property` set to the specific `value` and re
 
 ## API design principles
 
-Giant monolithic API docs can overwhelm anyone. By filtering what is most relevant to the audience, they can focus on what is most relevant and not be overwhelmed or distracted by all of the other API operations.
+Giant monolithic API docs can be overwhelming. By filtering what is most relevant to the audience, they can focus on what is most relevant and not be overwhelmed or distracted by all of the other API operations.
 
 ## Configuration
 
@@ -14,23 +14,59 @@ Giant monolithic API docs can overwhelm anyone. By filtering what is most releva
 | value         | [string] | **REQUIRED.** List of values used for the matching.                                                                                                                     |
 | matchStrategy | string   | Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`. |
 
-Example of configuration:
+## Examples
+
+Using the [Museum API](https://github.com/Redocly/museum-openapi-example) (v1.0.0), use the stats command to get a summary of its contents:
+
+```bash
+redocly stats openapi.yaml
+```
+
+I'm interested in the paths and operations in particular:
+
+- Path Items: 5
+- Operations: 8
+
+To restrict an OpenAPI description to only a few endpoints, this example uses `operationId` with a list of permitted values. To configure this, add the following to `redocly.yaml`:
+
+```yaml
+apis:
+  filter:
+    root: openapi.yaml
+    decorators:
+      filter-in:
+        property: operationId
+        value: [createSpecialEvent, listSpecialEvents]
+```
+
+To apply the decorator, use the `bundle` command:
+
+```bash
+redocly bundle filter -o museum-events.yaml
+```
+
+Looking through the resulting file, only the named operations are listed in the `paths` section, and running the `stats` command again shows that the filtered API description contains:
+
+- Path Items: 1
+- Operations: 2
+
+This approach allows you to publish sections of your API, without needing to share the entire thing with every consumer, or maintain multiple API descriptions for those different audiences.
+
+You can also use `filter-in` on other elements, such as parameters, responses, or other OpenAPI items.The example `redocly.yaml` shown below includes everything from the OpenAPI description that has an `x-audience` property set to either "Public" or "Partner":
 
 ```yaml
 decorators:
   filter-in:
     property: x-audience
     value: [Public, Partner]
-    matchStrategy: any
 ```
 
-## Examples
-
-Would you like examples? We would! They are coming soon.
+Use the filter decorators so that you can maintain one complete source of truth in OpenAPI format, then prepare restricted documents as appropriate for downstream tools such as API reference documentation.
 
 ## Related decorators
 
 - [filter-out](./filter-out.md)
+- [remove-x-internal](./remove-x-internal.md)
 
 ## Resources
 

docs/decorators/filter-out.md

@@ -5,7 +5,7 @@ Nodes that don't have the `property` defined are not impacted.
 
 ## API design principles
 
-Giant monolithic API docs can overwhelm anyone. By filtering what is most relevant to the audience, they can focus on what is most relevant and not be overwhelmed or distracted by all of the other API operations.
+Giant monolithic API docs can be overwhelming. By filtering what is most relevant to the audience, they can focus on what is most relevant and not be overwhelmed or distracted by all of the other API operations.
 
 ## Configuration
 
@@ -15,23 +15,57 @@ Giant monolithic API docs can overwhelm anyone. By filtering what is most releva
 | value         | [string] | **REQUIRED.** List of values used for the matching.                                                                                                                     |
 | matchStrategy | string   | Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`. |
 
-Example of configuration:
+## Examples
+
+Using the [Museum API](https://github.com/Redocly/museum-openapi-example) (v1.0.0), use the stats command to get a summary of its contents:
+
+```bash
+redocly stats openapi.yaml
+```
+
+I'm interested in the paths and operations in particular:
+
+- Path Items: 5
+- Operations: 8
+
+This example filters out all the endpoints tagged "Events", and `redocly.yaml` looks like this:
+
+```yaml
+apis:
+  filterout:
+    root: openapi.yaml
+    decorators:
+      filter-out:
+        property: tags
+        value: Events
+```
+
+To apply the decorator to the OpenAPI description, run the `bundle` command, like this:
+
+```bash
+redocly bundle filterout -o museum-filtered.yaml
+```
+
+Open the output file, `museum-filtered.yaml`, and the endpoints relating to special events have all been removed. Repeat the `stats` command, and this time the numbers are reported as:
+
+- Path Items: 3
+- Operations: 3
+
+This filtered OpenAPI description can be used to publish documentation or in another part of your API lifecycle where a limited part of your API is needed. Use a single source of truth in an OpenAPI description and allow the filtering to create the reduced version, rather than maintaining two API descriptions.
+
+You can also use the `filter-out` decorator on arbitrary properties that appear inside any OpenAPI object. For example, the following configuration looks for a property `x-audience` and removes any elements that have this property set to "Internal". Using this approach, you can remove specific parameters, responses, or endpoints from your OpenAPI description.
 
 ```yaml
 decorators:
   filter-out:
     property: x-audience
     value: Internal
-    matchStrategy: any
 ```
 
-## Examples
-
-Would you like examples? We would! They are coming soon.
-
 ## Related decorators
 
 - [filter-in](./filter-in.md)
+- [remove-x-internal](./remove-x-internal.md)
 
 ## Resources