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 endif
# OS-specific flags # OS-specific flags
TEST_FLAGS := -race TEST_FLAGS := --race -v
ifeq ($(OS),Windows_NT) ifeq ($(OS),Windows_NT)
TEST_FLAGS := TEST_FLAGS :=
endif endif
@ -166,7 +166,7 @@ test-js:
npm run test --prefix client npm run test --prefix client
test-go: test-go:
go test $(TEST_FLAGS) -v -coverprofile=coverage.txt -covermode=atomic ./... go test $(TEST_FLAGS) --coverprofile coverage.txt ./...
ci: client_with_deps ci: client_with_deps
go mod download go mod download

View File

@ -26,10 +26,10 @@ func isValidURL(rawurl string) bool {
url, err := url.ParseRequestURI(rawurl) url, err := url.ParseRequestURI(rawurl)
if err != nil { if err != nil {
return false //Couldn't even parse the rawurl return false // Couldn't even parse the rawurl
} }
if len(url.Scheme) == 0 { if len(url.Scheme) == 0 {
return false //No Scheme found return false // No Scheme found
} }
return true 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) { func (f *Filtering) handleFilteringRemoveURL(w http.ResponseWriter, r *http.Request) {
type request struct { type request struct {
URL string `json:"url"` URL string `json:"url"`
Whitelist bool `json:"whitelist"` Whitelist bool `json:"whitelist"`
} }
req := request{} req := request{}
err := json.NewDecoder(r.Body).Decode(&req) err := json.NewDecoder(r.Body).Decode(&req)
if err != nil { 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 return
} }
// go through each element and delete if url matches
config.Lock() config.Lock()
newFilters := []filter{}
filters := &config.Filters filters := &config.Filters
if req.Whitelist { if req.Whitelist {
filters = &config.WhitelistFilters 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 {
newFilters = append(newFilters, f)
continue
}
deleted = f
path := f.Path()
err = os.Rename(path, path+".old")
if err != nil { if err != nil {
log.Error("os.Rename: %s: %s", filter.Path(), err) log.Error("deleting filter %q: %s", path, err)
} }
} }
}
// Update the configuration after removing filter files
*filters = newFilters *filters = newFilters
config.Unlock() config.Unlock()
onConfigModified() onConfigModified()
enableFilters(true) 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 { 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` 1. `yarn install`
2. `yarn start` 2. `yarn start`
3. Open `http://localhost:4000/` 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 type: object
description: Filtering URL settings description: Filtering URL settings
properties: properties:
data:
properties:
enabled:
type: boolean
name:
type: string
url: url:
type: string type: string
enabled: type: object
url:
type: string
whitelist:
type: boolean type: boolean
FilterRefreshRequest: FilterRefreshRequest:
type: object type: object
@ -1466,6 +1475,8 @@ components:
description: URL or an absolute path to the file containing filtering rules description: URL or an absolute path to the file containing filtering rules
type: string type: string
example: https://filters.adtidy.org/windows/filters/15.txt example: https://filters.adtidy.org/windows/filters/15.txt
whitelist:
type: boolean
RemoveUrlRequest: RemoveUrlRequest:
type: object type: object
description: /remove_url request data description: /remove_url request data