Pull request: * home, openapi: improve docs and responses

Merge in DNS/adguard-home from 2243-better-docs to master

Closes #2243.

Squashed commit of the following:

commit 26c655a0e4339528870633c2cdf39c3b5c486b1d
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Nov 5 12:51:43 2020 +0300

    * openapi: improve more

commit dc0ab9857787d14eb0686814a4f3c8f917698bee
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Tue Nov 3 20:40:32 2020 +0300

    * home, openapi: improve docs and responses

Makefile

@@ -109,7 +109,7 @@ $(error DOCKER_IMAGE_NAME value is not set)
 endif
 
 # OS-specific flags
-TEST_FLAGS := -race
+TEST_FLAGS := --race -v
 ifeq ($(OS),Windows_NT)
 	TEST_FLAGS :=
 endif
@@ -166,7 +166,7 @@ test-js:
 	npm run test --prefix client
 
 test-go:
-	go test $(TEST_FLAGS) -v -coverprofile=coverage.txt -covermode=atomic ./...
+	go test $(TEST_FLAGS) --coverprofile coverage.txt ./...
 
 ci: client_with_deps
 	go mod download

internal/home/control_filtering.go

@@ -26,10 +26,10 @@ func isValidURL(rawurl string) bool {
 
 	url, err := url.ParseRequestURI(rawurl)
 	if err != nil {
-		return false //Couldn't even parse the rawurl
+		return false // Couldn't even parse the rawurl
 	}
 	if len(url.Scheme) == 0 {
-		return false //No Scheme found
+		return false // No Scheme found
 	}
 	return true
 }
@@ -95,44 +95,57 @@ func (f *Filtering) handleFilteringAddURL(w http.ResponseWriter, r *http.Request
 }
 
 func (f *Filtering) handleFilteringRemoveURL(w http.ResponseWriter, r *http.Request) {
-
 	type request struct {
 		URL       string `json:"url"`
 		Whitelist bool   `json:"whitelist"`
 	}
+
 	req := request{}
 	err := json.NewDecoder(r.Body).Decode(&req)
 	if err != nil {
-		httpError(w, http.StatusBadRequest, "Failed to parse request body json: %s", err)
+		httpError(w, http.StatusBadRequest, "failed to parse request body json: %s", err)
 		return
 	}
 
-	// go through each element and delete if url matches
 	config.Lock()
-	newFilters := []filter{}
 	filters := &config.Filters
 	if req.Whitelist {
 		filters = &config.WhitelistFilters
 	}
-	for _, filter := range *filters {
+
-		if filter.URL != req.URL {
+	var deleted filter
-			newFilters = append(newFilters, filter)
+	var newFilters []filter
-		} else {
+	for _, f := range *filters {
-			err := os.Rename(filter.Path(), filter.Path()+".old")
+		if f.URL != req.URL {
-			if err != nil {
+			newFilters = append(newFilters, f)
-				log.Error("os.Rename: %s: %s", filter.Path(), err)
+
-			}
+			continue
+		}
+
+		deleted = f
+		path := f.Path()
+		err = os.Rename(path, path+".old")
+		if err != nil {
+			log.Error("deleting filter %q: %s", path, err)
 		}
 	}
-	// Update the configuration after removing filter files
+
 	*filters = newFilters
 	config.Unlock()
 
 	onConfigModified()
 	enableFilters(true)
 
-	// Note: the old files "filter.txt.old" aren't deleted - it's not really necessary,
+	// NOTE: The old files "filter.txt.old" aren't deleted.  It's not really
-	//  but will require the additional code to run after enableFilters() is finished: i.e. complicated
+	// necessary, but will require the additional complicated code to run
+	// after enableFilters is done.
+	//
+	// TODO(a.garipov): Make sure the above comment is true.
+
+	_, err = fmt.Fprintf(w, "OK %d rules\n", deleted.RulesCount)
+	if err != nil {
+		httpError(w, http.StatusInternalServerError, "couldn't write body: %s", err)
+	}
 }
 
 type filterURLJSON struct {

openapi/README.md

@@ -1,25 +1,35 @@
-## AdGuard Home OpenAPI
+# AdGuard Home OpenAPI
 
-We are using [OpenAPI specification](https://swagger.io/docs/specification/about/) to generate AdGuard Home API specification.
+We are using
+[OpenAPI specification](https://swagger.io/docs/specification/about/)
+to generate AdGuard Home API specification.
 
-### How to edit the API spec
+## How To Edit The API Spec
 
-The easiest way would be to use [Swagger Editor](http://editor.swagger.io/) and just copy/paste the YAML file there.
+The easiest way would be to use
+[Swagger Editor](http://editor.swagger.io/)
+and just copy/paste the YAML file there.
 
-### How to read the API doc
+## How To Read The API Doc
 
 1. `yarn install`
 2. `yarn start`
 3. Open `http://localhost:4000/`
 
-### Changelog
+## Changelog
 
-[Here](CHANGELOG.md) we keep track of all non-compatible changes that are being made.
+[Here](CHANGELOG.md) we keep track of all non-compatible changes that are being
+made.
 
-### Authentication
+## Authentication
 
-If AdGuard Home's web user is password-protected, a web client must use authentication mechanism when sending requests to server.  Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests:
+If AdGuard Home's web user is password-protected, a web client must use
+authentication mechanism when sending requests to server.  Basic access
+authentication is the most simple method - a client must pass `Authorization`
+HTTP header along with all requests:
 
-    Authorization: Basic BASE64_DATA
+```http
+Authorization: Basic BASE64_DATA
+```
 
-where BASE64_DATA is base64-encoded data for `username:password` string.
+Where BASE64_DATA is base64-encoded data for `username:password` string.

openapi/openapi.yaml

@@ -1137,9 +1137,18 @@ components:
             type: object
             description: Filtering URL settings
             properties:
+                data:
+                    properties:
+                        enabled:
+                            type: boolean
+                        name:
+                            type: string
+                        url:
+                            type: string
+                    type: object
                 url:
                     type: string
-                enabled:
+                whitelist:
                     type: boolean
         FilterRefreshRequest:
             type: object
@@ -1466,6 +1475,8 @@ components:
                     description: URL or an absolute path to the file containing filtering rules
                     type: string
                     example: https://filters.adtidy.org/windows/filters/15.txt
+                whitelist:
+                    type: boolean
         RemoveUrlRequest:
             type: object
             description: /remove_url request data