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
This commit is contained in:
Ainar Garipov 2020-11-05 13:59:57 +03:00
parent 62cc334f46
commit 02d16a0b40
4 changed files with 65 additions and 31 deletions

View file

@ -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

View file

@ -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 {
newFilters = append(newFilters, filter)
} else {
err := os.Rename(filter.Path(), filter.Path()+".old")
if err != nil {
log.Error("os.Rename: %s: %s", filter.Path(), err)
}
var deleted filter
var newFilters []filter
for _, f := range *filters {
if f.URL != req.URL {
newFilters = append(newFilters, f)
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,
// but will require the additional code to run after enableFilters() is finished: i.e. complicated
// NOTE: The old files "filter.txt.old" aren't deleted. It's not really
// 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 {

View file

@ -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.

View file

@ -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