You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by me...@apache.org on 2021/02/22 15:57:36 UTC
[apisix-dashboard] branch master updated: chore: update doc about
JSONSchema sync and remove useless codes (#1486)
This is an automated email from the ASF dual-hosted git repository.
membphis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-dashboard.git
The following commit(s) were added to refs/heads/master by this push:
new eba0868 chore: update doc about JSONSchema sync and remove useless codes (#1486)
eba0868 is described below
commit eba0868ae13696753caf2ae028fc24ec1d014b8c
Author: nic-chen <33...@users.noreply.github.com>
AuthorDate: Mon Feb 22 23:57:26 2021 +0800
chore: update doc about JSONSchema sync and remove useless codes (#1486)
close #1443
---
api/build-tools/json.lua | 400 ----------------------------------------
api/build-tools/schema-sync.lua | 160 ----------------
api/build-tools/schema-sync.sh | 49 -----
api/test/docker/Dockerfile | 2 -
docs/FAQ.md | 22 +--
docs/deploy.md | 16 ++
6 files changed, 25 insertions(+), 624 deletions(-)
diff --git a/api/build-tools/json.lua b/api/build-tools/json.lua
deleted file mode 100644
index 720b029..0000000
--- a/api/build-tools/json.lua
+++ /dev/null
@@ -1,400 +0,0 @@
---
--- json.lua
---
--- Copyright (c) 2020 rxi
---
--- Permission is hereby granted, free of charge, to any person obtaining a copy of
--- this software and associated documentation files (the "Software"), to deal in
--- the Software without restriction, including without limitation the rights to
--- use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
--- of the Software, and to permit persons to whom the Software is furnished to do
--- so, subject to the following conditions:
---
--- The above copyright notice and this permission notice shall be included in all
--- copies or substantial portions of the Software.
---
--- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
--- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
--- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
--- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
--- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
--- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
--- SOFTWARE.
---
-local string = string
-local error = error
-local rawget = rawget
-local next = next
-local pairs = pairs
-local type = type
-local ipairs = ipairs
-local table = table
-local math = math
-local tostring = tostring
-local select = select
-local tonumber = tonumber
-
-local json = { _version = "0.1.2" }
-
--------------------------------------------------------------------------------
--- Encode
--------------------------------------------------------------------------------
-
-local encode
-
-local escape_char_map = {
- [ "\\" ] = "\\",
- [ "\"" ] = "\"",
- [ "\b" ] = "b",
- [ "\f" ] = "f",
- [ "\n" ] = "n",
- [ "\r" ] = "r",
- [ "\t" ] = "t",
-}
-
-local escape_char_map_inv = { [ "/" ] = "/" }
-for k, v in pairs(escape_char_map) do
- escape_char_map_inv[v] = k
-end
-
-
-local function escape_char(c)
- return "\\" .. (escape_char_map[c] or string.format("u%04x", c:byte()))
-end
-
-
-local function encode_nil(val)
- return "null"
-end
-
-
-local function encode_table(val, stack)
- local res = {}
- stack = stack or {}
-
- -- Circular reference?
- if stack[val] then error("circular reference") end
-
- stack[val] = true
-
- if rawget(val, 1) ~= nil or next(val) == nil then
- -- Treat as array -- check keys are valid and it is not sparse
- local n = 0
- for k in pairs(val) do
- if type(k) ~= "number" then
- error("invalid table: mixed or invalid key types")
- end
- n = n + 1
- end
- if n ~= #val then
- error("invalid table: sparse array")
- end
- -- Encode
- for i, v in ipairs(val) do
- table.insert(res, encode(v, stack))
- end
- stack[val] = nil
- return "[" .. table.concat(res, ",") .. "]"
-
- else
- -- Treat as an object
- for k, v in pairs(val) do
- if type(k) ~= "string" then
- error("invalid table: mixed or invalid key types")
- end
- table.insert(res, encode(k, stack) .. ":" .. encode(v, stack))
- end
- stack[val] = nil
- return "{" .. table.concat(res, ",") .. "}"
- end
-end
-
-
-local function encode_string(val)
- return '"' .. val:gsub('[%z\1-\31\\"]', escape_char) .. '"'
-end
-
-
-local function encode_number(val)
- -- Check for NaN, -inf and inf
- if val ~= val or val <= -math.huge or val >= math.huge then
- error("unexpected number value '" .. tostring(val) .. "'")
- end
- return string.format("%.14g", val)
-end
-
-
-local type_func_map = {
- [ "nil" ] = encode_nil,
- [ "table" ] = encode_table,
- [ "string" ] = encode_string,
- [ "number" ] = encode_number,
- [ "boolean" ] = tostring,
-}
-
-
-encode = function(val, stack)
- local t = type(val)
- local f = type_func_map[t]
- if f then
- return f(val, stack)
- end
- error("unexpected type '" .. t .. "'")
-end
-
-
-function json.encode(val)
- return ( encode(val) )
-end
-
-
--------------------------------------------------------------------------------
--- Decode
--------------------------------------------------------------------------------
-
-local parse
-
-local function create_set(...)
- local res = {}
- for i = 1, select("#", ...) do
- res[ select(i, ...) ] = true
- end
- return res
-end
-
-local space_chars = create_set(" ", "\t", "\r", "\n")
-local delim_chars = create_set(" ", "\t", "\r", "\n", "]", "}", ",")
-local escape_chars = create_set("\\", "/", '"', "b", "f", "n", "r", "t", "u")
-local literals = create_set("true", "false", "null")
-
-local literal_map = {
- [ "true" ] = true,
- [ "false" ] = false,
- [ "null" ] = nil,
-}
-
-
-local function next_char(str, idx, set, negate)
- for i = idx, #str do
- if set[str:sub(i, i)] ~= negate then
- return i
- end
- end
- return #str + 1
-end
-
-
-local function decode_error(str, idx, msg)
- local line_count = 1
- local col_count = 1
- for i = 1, idx - 1 do
- col_count = col_count + 1
- if str:sub(i, i) == "\n" then
- line_count = line_count + 1
- col_count = 1
- end
- end
- error( string.format("%s at line %d col %d", msg, line_count, col_count) )
-end
-
-
-local function codepoint_to_utf8(n)
- -- http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=iws-appendixa
- local f = math.floor
- if n <= 0x7f then
- return string.char(n)
- elseif n <= 0x7ff then
- return string.char(f(n / 64) + 192, n % 64 + 128)
- elseif n <= 0xffff then
- return string.char(f(n / 4096) + 224, f(n % 4096 / 64) + 128, n % 64 + 128)
- elseif n <= 0x10ffff then
- return string.char(f(n / 262144) + 240, f(n % 262144 / 4096) + 128,
- f(n % 4096 / 64) + 128, n % 64 + 128)
- end
- error( string.format("invalid unicode codepoint '%x'", n) )
-end
-
-
-local function parse_unicode_escape(s)
- local n1 = tonumber( s:sub(1, 4), 16 )
- local n2 = tonumber( s:sub(7, 10), 16 )
- -- Surrogate pair?
- if n2 then
- return codepoint_to_utf8((n1 - 0xd800) * 0x400 + (n2 - 0xdc00) + 0x10000)
- else
- return codepoint_to_utf8(n1)
- end
-end
-
-
-local function parse_string(str, i)
- local res = ""
- local j = i + 1
- local k = j
-
- while j <= #str do
- local x = str:byte(j)
-
- if x < 32 then
- decode_error(str, j, "control character in string")
-
- elseif x == 92 then -- `\`: Escape
- res = res .. str:sub(k, j - 1)
- j = j + 1
- local c = str:sub(j, j)
- if c == "u" then
- local hex = str:match("^[dD][89aAbB]%x%x\\u%x%x%x%x", j + 1)
- or str:match("^%x%x%x%x", j + 1)
- or decode_error(str, j - 1, "invalid unicode escape in string")
- res = res .. parse_unicode_escape(hex)
- j = j + #hex
- else
- if not escape_chars[c] then
- decode_error(str, j - 1, "invalid escape char '" .. c .. "' in string")
- end
- res = res .. escape_char_map_inv[c]
- end
- k = j + 1
-
- elseif x == 34 then -- `"`: End of string
- res = res .. str:sub(k, j - 1)
- return res, j + 1
- end
-
- j = j + 1
- end
-
- decode_error(str, i, "expected closing quote for string")
-end
-
-
-local function parse_number(str, i)
- local x = next_char(str, i, delim_chars)
- local s = str:sub(i, x - 1)
- local n = tonumber(s)
- if not n then
- decode_error(str, i, "invalid number '" .. s .. "'")
- end
- return n, x
-end
-
-
-local function parse_literal(str, i)
- local x = next_char(str, i, delim_chars)
- local word = str:sub(i, x - 1)
- if not literals[word] then
- decode_error(str, i, "invalid literal '" .. word .. "'")
- end
- return literal_map[word], x
-end
-
-
-local function parse_array(str, i)
- local res = {}
- local n = 1
- i = i + 1
- while 1 do
- local x
- i = next_char(str, i, space_chars, true)
- -- Empty / end of array?
- if str:sub(i, i) == "]" then
- i = i + 1
- break
- end
- -- Read token
- x, i = parse(str, i)
- res[n] = x
- n = n + 1
- -- Next token
- i = next_char(str, i, space_chars, true)
- local chr = str:sub(i, i)
- i = i + 1
- if chr == "]" then break end
- if chr ~= "," then decode_error(str, i, "expected ']' or ','") end
- end
- return res, i
-end
-
-
-local function parse_object(str, i)
- local res = {}
- i = i + 1
- while 1 do
- local key, val
- i = next_char(str, i, space_chars, true)
- -- Empty / end of object?
- if str:sub(i, i) == "}" then
- i = i + 1
- break
- end
- -- Read key
- if str:sub(i, i) ~= '"' then
- decode_error(str, i, "expected string for key")
- end
- key, i = parse(str, i)
- -- Read ':' delimiter
- i = next_char(str, i, space_chars, true)
- if str:sub(i, i) ~= ":" then
- decode_error(str, i, "expected ':' after key")
- end
- i = next_char(str, i + 1, space_chars, true)
- -- Read value
- val, i = parse(str, i)
- -- Set
- res[key] = val
- -- Next token
- i = next_char(str, i, space_chars, true)
- local chr = str:sub(i, i)
- i = i + 1
- if chr == "}" then break end
- if chr ~= "," then decode_error(str, i, "expected '}' or ','") end
- end
- return res, i
-end
-
-
-local char_func_map = {
- [ '"' ] = parse_string,
- [ "0" ] = parse_number,
- [ "1" ] = parse_number,
- [ "2" ] = parse_number,
- [ "3" ] = parse_number,
- [ "4" ] = parse_number,
- [ "5" ] = parse_number,
- [ "6" ] = parse_number,
- [ "7" ] = parse_number,
- [ "8" ] = parse_number,
- [ "9" ] = parse_number,
- [ "-" ] = parse_number,
- [ "t" ] = parse_literal,
- [ "f" ] = parse_literal,
- [ "n" ] = parse_literal,
- [ "[" ] = parse_array,
- [ "{" ] = parse_object,
-}
-
-
-parse = function(str, idx)
- local chr = str:sub(idx, idx)
- local f = char_func_map[chr]
- if f then
- return f(str, idx)
- end
- decode_error(str, idx, "unexpected character '" .. chr .. "'")
-end
-
-
-function json.decode(str)
- if type(str) ~= "string" then
- error("expected argument of type string, got " .. type(str))
- end
- local res, idx = parse(str, next_char(str, 1, space_chars, true))
- idx = next_char(str, idx, space_chars, true)
- if idx <= #str then
- decode_error(str, idx, "trailing garbage")
- end
- return res
-end
-
-
-return json
diff --git a/api/build-tools/schema-sync.lua b/api/build-tools/schema-sync.lua
deleted file mode 100644
index 74271cf..0000000
--- a/api/build-tools/schema-sync.lua
+++ /dev/null
@@ -1,160 +0,0 @@
---
--- Licensed to the Apache Software Foundation (ASF) under one or more
--- contributor license agreements. See the NOTICE file distributed with
--- this work for additional information regarding copyright ownership.
--- The ASF licenses this file to You under the Apache License, Version 2.0
--- (the "License"); you may not use this file except in compliance with
--- the License. You may obtain a copy of the License at
---
--- http://www.apache.org/licenses/LICENSE-2.0
---
--- Unless required by applicable law or agreed to in writing, software
--- distributed under the License is distributed on an "AS IS" BASIS,
--- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
--- See the License for the specific language governing permissions and
--- limitations under the License.
---
-local json = require("json")
-
--- simulate loading modules to avoid errors that will cause fail to read json schema
-local fake_module_list = {
- 'cjson',
- 'cjson.safe',
- 'bit',
- 'lfs',
- 'ngx.worker',
- 'ngx.errlog',
- 'ngx.process',
- 'ngx.re',
- 'ngx.ssl',
- 'net.url',
- 'opentracing.tracer',
- 'pb',
- 'prometheus',
- 'protoc',
- 'skywalking.tracer',
-
- 'resty.cookie',
- 'resty.core.regex',
- 'resty.core.base',
- 'resty.hmac',
- 'resty.http',
- 'resty.ipmatcher',
- 'resty.jit-uuid',
- 'resty.jwt',
- 'resty.kafka.producer',
- 'resty.limit.count',
- 'resty.limit.conn',
- 'resty.limit.req',
- 'resty.logger.socket',
- 'resty.lock',
- 'resty.openidc',
- 'resty.random',
- 'resty.redis',
- 'resty.rediscluster',
- 'resty.signal',
- 'resty.string',
- 'resty.aes',
- 'resty.radixtree',
- 'resty.expr.v1',
-
- 'apisix.consumer',
- 'apisix.core.json',
- 'apisix.core.schema',
- 'apisix.upstream',
- 'apisix.utils.log-util',
- 'apisix.utils.batch-processor',
- 'apisix.plugin',
- 'apisix.plugins.skywalking.client',
- 'apisix.plugins.skywalking.tracer',
- 'apisix.plugins.zipkin.codec',
- 'apisix.plugins.zipkin.random_sampler',
- 'apisix.plugins.zipkin.reporter',
- 'apisix.timers'
-}
-for _, name in ipairs(fake_module_list) do
- package.loaded[name] = {}
-end
-
-
-local empty_function = function()
-end
-
-
-ngx = {}
-ngx.re = {}
-ngx.timer = {}
-ngx.location = {}
-ngx.socket = {}
-ngx.thread = {}
-ngx.worker = {}
-ngx.re.gmatch = empty_function
-ngx.req = {}
-ngx.config = {}
-ngx.shared = {
- ["plugin-api-breaker"] = {}
-}
-ngx.shared.internal_status = {}
-
--- additional define for management
-local time_def = {
- type = "integer",
-}
-local schema = require("apisix.schema_def")
-for _, resource in ipairs({"ssl", "route", "service", "upstream", "consumer"}) do
- schema[resource].properties.create_time = time_def
- schema[resource].properties.update_time = time_def
-end
-schema.ssl.properties.validity_start = time_def
-schema.ssl.properties.validity_end = time_def
-
-package.loaded["apisix.core"] = {
- lrucache = {
- new = empty_function
- },
- schema = schema,
- id = {
- get = empty_function
- },
- table = {
- insert = empty_function
- },
- string = {},
- version = {
- VERSION = ""
- }
-}
-
-
-function get_plugin_list()
- local all = io.popen("ls apisix/plugins");
- local list = {};
- for filename in all:lines() do
- suffix = string.sub(filename, -4)
- if suffix == ".lua" then
- table.insert(list, string.sub(filename, 1, -5))
- end
- end
- all:close()
- return list
-end
-
-
-local schema_all = {}
-schema_all.main = schema
-schema_all.plugins = {}
-
-local plugins = get_plugin_list()
-for idx, plugin_name in pairs(plugins) do
- local plugin = require("apisix.plugins." .. plugin_name)
- if plugin and type(plugin) == "table" and plugin.schema then
- schema_all.plugins[plugin_name]= {
- ['schema'] = plugin.schema
- }
- end
- if plugin and type(plugin) == "table" and plugin.consumer_schema then
- schema_all.plugins[plugin_name]['consumer_schema'] = plugin.consumer_schema
- end
-end
-
-print(json.encode(schema_all))
diff --git a/api/build-tools/schema-sync.sh b/api/build-tools/schema-sync.sh
deleted file mode 100755
index 53e1b25..0000000
--- a/api/build-tools/schema-sync.sh
+++ /dev/null
@@ -1,49 +0,0 @@
-#!/usr/bin/env bash
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-
-set -ex
-
-pwd=`pwd`
-
-if [[ -n $1 && -d "$1" ]]; then
- path=$1
- if [[ -d "${path}/apisix" ]]; then
- cp -R ${path}/apisix/ ./api/build-tools/apisix/
- else
- cp -R ${path}/ ./api/build-tools/apisix/
- fi
-else
- version="master"
- if [[ -n $1 ]]; then
- version=$1
- fi
- wget -O $version.zip https://github.com/apache/apisix/archive/$version.zip
-
- unzip $version.zip
- mkdir -p ./api/build-tools/apisix/
- cp -a ./apisix-$version/apisix/. ./api/build-tools/apisix/
- ls -l ./api/build-tools/apisix/
- rm -rf ./apisix-$version
-fi
-
-cd ./api/build-tools/ && lua schema-sync.lua > ${pwd}/api/conf/schema.json && cd ../../
-
-rm -rf ./api/build-tools/apisix/
-
-echo "sync success:"
-echo "${pwd}/api/conf/schema.json"
diff --git a/api/test/docker/Dockerfile b/api/test/docker/Dockerfile
index 6374393..6b8bf2f 100644
--- a/api/test/docker/Dockerfile
+++ b/api/test/docker/Dockerfile
@@ -22,10 +22,8 @@ WORKDIR /go/src/github.com/apisix/manager-api
COPY ./ ./
RUN mkdir -p /go/manager-api/conf \
- && mkdir -p /go/manager-api/build-tools \
&& go test -c -cover -covermode=atomic -o /go/manager-api/manager-api -coverpkg "./..." ./cmd/manager \
&& mv /go/src/github.com/apisix/manager-api/entry.sh /go/manager-api/ \
- && mv /go/src/github.com/apisix/manager-api/build-tools/* /go/manager-api/build-tools/ \
&& mv /go/src/github.com/apisix/manager-api/conf/conf.yaml /go/manager-api/conf/conf.yaml \
&& mv /go/src/github.com/apisix/manager-api/conf/schema.json /go/manager-api/conf/schema.json \
&& rm -rf /go/src/github.com/apisix/manager-api \
diff --git a/docs/FAQ.md b/docs/FAQ.md
index e4996e7..2218473 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -33,27 +33,23 @@ If you are using Apache APISIX below v2.0, be aware that the data from the etcd
### 4. After modifying the plugin schema or creating a custom plugin in Apache APISIX, why can't I find it on the dashboard?
-Since the Dashboard caches the jsonschema data of the plugins in Apache APISIX, you need to synchronize the data in the Dashboard after you create your custom plugins in Apache APISIX, which currently **only supports manual operation**, this issue will be optimized in the following versions. Please follow the following guide.
+Since the Dashboard caches the jsonschema data of the plugins in Apache APISIX, you need to synchronize the data in the Dashboard after you create your custom plugins in Apache APISIX, which currently **only supports manual operation**. Please follow the following guide.
-1. Install [Lua](https://www.lua.org/download.html) and `zip`.
+1. Confirm that your APISIX is running and has enabled control API (enabled by default and only runs local access)
+Refer to the beginning in:
+https://github.com/apache/apisix/blob/master/doc/control-api.md
-2. Execute the following commands.
+2. Execute the following commands to export jsonchema on your APISIX server (if it is configured for non-local access, it does not need to be executed on your APISIX server, and the access IP and port should be modified accordingly)
```sh
-# `$version` is the version number of Apache APISIX, e.g. master or 2.1.
-$ api/build-tools/schema-sync.sh $version
+curl 127.0.0.1:9090/v1/schema > schema.json
```
-If you have a custom plugin, make sure it is in the `apisix` directory and use the following command.
+Refer to https://github.com/apache/apisix/blob/master/doc/control-api.md#get-v1schema
-```sh
-$ api/build-tools/schema-sync.sh /path/to/apisix
-
-# e.g
-$ api/build-tools/schema-sync.sh /usr/local/apisix
-```
+3. Copy the exported `schema.json` to the `conf` directory in the Dashboard working directory (About working directory, please refer to https://github.com/apache/apisix-dashboard/blob/master/docs/deploy.md#working-directory)
-After the command finishes executing, if you are using a binary `manager-api` that has already been built, you will need to manually copy `api/conf/schema.json` to the `conf` directory under the Dashboard **working directory**. where **working directory** refers to the `conf` directory under this [document](./deploy.md) is the `output` directory, or the directory with the modified name, that is generated in the root directory after the build is complete.
+4. Restart the Manager API
### 5. How to write API documentation
diff --git a/docs/deploy.md b/docs/deploy.md
index 4b4b756..611145a 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -86,3 +86,19 @@ run:
```sh
$ ./manager-api stop
```
+
+## Working directory
+
+the `output` directory mention above is the default working directory.
+
+You can move the entire directory to any path you want, and use the `-p` to specify it as the working directory.
+
+For example, you can move it to `/usr/local/apisix-dashboard/`
+
+```sh
+$ mv ./output/manager-api /usr/local/bin/
+
+$ mv ./output/ /usr/local/apisix-dashboard/
+
+$ manager-api -p /usr/local/apisix-dashboard/
+```