all: improve documentation

AGHTechDoc.md

@@ -1833,16 +1833,22 @@ Response:
 	200 OK
 
 	{
-	"reason":"FilteredBlackList",
-	"filter_id":1,
-	"rule":"||doubleclick.net^",
-	"service_name": "...", // set if reason=FilteredBlockedService
-
-	// if reason=ReasonRewrite:
-	"cname": "...",
-	"ip_addrs": ["1.2.3.4", ...],
+		"reason":"FilteredBlackList",
+		"rules":{
+			"filter_list_id":42,
+			"text":"||doubleclick.net^",
+		},
+		// If we have "reason":"FilteredBlockedService".
+		"service_name": "...",
+		// If we have "reason":"Rewrite".
+		"cname": "...",
+		"ip_addrs": ["1.2.3.4", ...]
 	}
 
+There are also deprecated properties `filter_id` and `rule` on the top level of
+the response object.  Their usaga should be replaced with
+`rules[*].filter_list_id` and `rules[*].text` correspondingly.  See the
+_OpenAPI_ documentation and the `./openapi/CHANGELOG.md` file.
 
 ## Log-in page
 

internal/dnsfilter/dnsfilter.go

@@ -160,19 +160,20 @@ const (
 // TODO(a.garipov): Resync with actual code names or replace completely
 // in HTTP API v1.
 var reasonNames = []string{
-	"NotFilteredNotFound",
-	"NotFilteredWhiteList",
-	"NotFilteredError",
-
-	"FilteredBlackList",
-	"FilteredSafeBrowsing",
-	"FilteredParental",
-	"FilteredInvalid",
-	"FilteredSafeSearch",
-	"FilteredBlockedService",
-
-	"Rewrite",
-	"RewriteEtcHosts",
+	NotFilteredNotFound:  "NotFilteredNotFound",
+	NotFilteredWhiteList: "NotFilteredWhiteList",
+	NotFilteredError:     "NotFilteredError",
+
+	FilteredBlackList:      "FilteredBlackList",
+	FilteredSafeBrowsing:   "FilteredSafeBrowsing",
+	FilteredParental:       "FilteredParental",
+	FilteredInvalid:        "FilteredInvalid",
+	FilteredSafeSearch:     "FilteredSafeSearch",
+	FilteredBlockedService: "FilteredBlockedService",
+
+	ReasonRewrite: "Rewrite",
+
+	RewriteAutoHosts: "RewriteEtcHosts",
 }
 
 func (r Reason) String() string {

openapi/CHANGELOG.md

@@ -1,5 +1,37 @@
 # AdGuard Home API Change Log
 
+<!-- TODO(a.garipov): Reformat in accordance with the KeepAChangelog spec. -->
+
+## v0.105: API changes
+
+### Multiple matched rules in `GET /filtering/check_host` and `GET /querylog`
+
+<!-- TODO(a.garipov): Update with better examples once $dnsrewrite rules are
+checked in. -->
+
+* The properties `rule` and `filter_id` are now deprecated.  API users should
+  inspect the newly-added `rules` object array instead.  Currently, it's either
+  empty or contains one object, which contains the same things as the old two
+  properties did, but under more correct names:
+
+  ```js
+  {
+    // …
+
+    // Deprecated.
+    "rule": "||example.com^",
+    // Deprecated.
+    "filter_id": 42,
+    // Newly-added.
+    "rules": [{
+      "text": "||example.com^",
+      "filter_list_id": 42
+    }]
+  }
+  ```
+
+  The old fields will be removed in v0.106.0.
+
 ## v0.103: API changes
 
 ### API: replace settings in GET /control/dns_info & POST /control/dns_config