document common params

COMMON-PARAMS.md

@@ -0,0 +1,36 @@
+## Common Parameters
+
+### Common Parameters Definition
+Parameters shared by all operations of a path can be defined on the path level instead of the operation level.  
+Path-level parameters are inherited by all operations of that path.  
+A typical use case are the GET/PUT/PATCH/DELETE operations that manipulate a resource accessed via a path parameter.
+
+### There are two ways to handle Common Parameters in oasdiff
+1. By default, oasdiff compares path parameters and operation parameters seperately.
+2. The `--flatten-params` merges common parameters from the path level into the operation level before running the diff.
+
+For example, this command outputs two breaking changes:
+```
+oasdiff changelog data/common-params/params_in_path.yaml data/common-params/params_in_op.yaml
+```
+Output: 
+```
+2 changes: 2 error, 0 warning, 0 info
+error	[new-request-path-parameter] at data/common-params/params_in_op.yaml
+	in API GET /admin/v0/abc/{id}
+		added the new path request parameter 'id'
+
+error	[new-required-request-parameter] at data/common-params/params_in_op.yaml
+	in API GET /admin/v0/abc/{id}
+		added the new required 'header' request parameter 'tenant-id'
+```
+
+
+Adding the `--flatten-params` eliminates the errors:
+```
+oasdiff changelog data/common-params/params_in_path.yaml data/common-params/params_in_op.yaml --flatten-params
+```
+
+
+
+

README.md

@@ -30,7 +30,7 @@ docker run --rm -t tufin/oasdiff changelog https://raw.githubusercontent.com/Tuf
 - [API deprecation](API-DEPRECATION.md)
 - [Multiple versions of the same endpoint](MATCHING-ENDPOINTS.md)
 - [Merge allOf schemas](ALLOF.md)
-- [Common Parameters](ALLOF.md)
+- [Merge common parameters](COMMON-PARAMS.md)
 - [Path prefix modification](#path-prefix-modification)
 - [Path parameter renaming](#path-parameter-renaming)
 - [Excluding certain kinds of changes](#excluding-specific-kinds-of-changes)