This is an automated email from the ASF dual-hosted git repository.
jin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-doc.git
The following commit(s) were added to refs/heads/master by this push:
new 62101543 doc: optimize description about preload, init-store and
others (#293)
62101543 is described below
commit 621015439f4573a179df7a5654b7d65c1c8c0973
Author: Dandelion <[email protected]>
AuthorDate: Wed Nov 1 21:52:52 2023 +0800
doc: optimize description about preload, init-store and others (#293)
Co-authored-by: imbajin <[email protected]>
* doc: add swagger link in api doc
---------
Co-authored-by: imbajin <[email protected]>
---
content/cn/docs/clients/restful-api/_index.md | 2 +
content/cn/docs/config/config-guide.md | 2 +-
.../621swaggerui\347\244\272\344\276\213.png" | Bin 0 -> 319057 bytes
content/cn/docs/quickstart/hugegraph-hubble.md | 10 ++++-
content/cn/docs/quickstart/hugegraph-server.md | 41 +++++++++++++--------
content/en/docs/clients/restful-api/_index.md | 4 +-
content/en/docs/config/config-guide.md | 2 +-
.../621swaggerui\347\244\272\344\276\213.png" | Bin 0 -> 319057 bytes
content/en/docs/quickstart/hugegraph-hubble.md | 14 +++++--
content/en/docs/quickstart/hugegraph-server.md | 33 +++++++++++------
10 files changed, 72 insertions(+), 36 deletions(-)
diff --git a/content/cn/docs/clients/restful-api/_index.md
b/content/cn/docs/clients/restful-api/_index.md
index 85788b66..b8c4fbfb 100644
--- a/content/cn/docs/clients/restful-api/_index.md
+++ b/content/cn/docs/clients/restful-api/_index.md
@@ -7,6 +7,8 @@ weight: 1
HugeGraph-Server通过HugeGraph-API基于HTTP协议为Client提供操作图的接口，主要包括元数据和
图数据的增删改查，遍历算法，变量，图操作及其他操作。
+除了下方的文档，你还可以通过 `localhost:8080/swagger-ui/index.html` 访问 `swagger-ui` 以查看
`RESTful API`。[示例可以参考此处](/cn/docs/quickstart/hugegraph-server#swaggerui-example)
+
[comment]: <> (- Graph Schema)
[comment]: <> ( - [Schema](restful-api/schema.md))
diff --git a/content/cn/docs/config/config-guide.md
b/content/cn/docs/config/config-guide.md
index 88de1afc..63b3c6ce 100644
--- a/content/cn/docs/config/config-guide.md
+++ b/content/cn/docs/config/config-guide.md
@@ -351,7 +351,7 @@ Initialization finished.
$ ./bin/start-hugegraph.sh
Starting HugeGraphServer...
-Connecting to HugeGraphServer (http://127.0.0.1:18080/graphs)...OK
+Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)...OK
Started [pid 21614]
```
diff --git
"a/content/cn/docs/images/images-server/621swaggerui\347\244\272\344\276\213.png"
"b/content/cn/docs/images/images-server/621swaggerui\347\244\272\344\276\213.png"
new file mode 100644
index 00000000..87a15481
Binary files /dev/null and
"b/content/cn/docs/images/images-server/621swaggerui\347\244\272\344\276\213.png"
differ
diff --git a/content/cn/docs/quickstart/hugegraph-hubble.md
b/content/cn/docs/quickstart/hugegraph-hubble.md
index 9b15ccc4..43522ddd 100644
--- a/content/cn/docs/quickstart/hugegraph-hubble.md
+++ b/content/cn/docs/quickstart/hugegraph-hubble.md
@@ -41,7 +41,9 @@ HugeGraph 是一款面向分析型，支持批量操作的图数据库系统，
#### 2.1 使用 Docker (推荐)
-> **特别注意**: 如果使用 docker 启动 hubble，且 hubble 和 server 位于同一宿主机，在后续 hubble 页面中设置
graph 的 hostname 的时候请不要直接设置 `localhost/127.0.0.1`，这将指向 hubble 容器内部而非宿主机，导致无法连接到
server. 如果 hubble 和 server 在同一 docker 网络下，则可以直接使用`container_name`作为主机名，端口则为
8080. 或者也可以使用宿主机 ip 作为主机名，此时端口号为宿主机为 server 配置的端口
+> **特别注意**: docker 模式下，若 hubble 和 server 在同一宿主机，hubble 页面中设置 graph 的
`hostname` **不能设置**为 `localhost/127.0.0.1`，因这会指向 hubble **容器内部**而非宿主机，导致无法连接到
server.
+>
+> 若 hubble 和 server 在同一 docker 网络下，**推荐**直接使用`container_name` (如下例的 `graph`)
作为主机名。或者也可以使用 **宿主机 IP** 作为主机名，此时端口号为宿主机给 server 配置的端口
我们可以使用 `docker run -itd --name=hubble -p 8088:8088 hugegraph/hubble` 快速启动
[hubble](https://hub.docker.com/r/hugegraph/hubble).
@@ -56,7 +58,7 @@ services:
image: hugegraph/hugegraph
container_name: graph
ports:
- - 18080:8080
+ - 8080:8080
hubble:
image: hugegraph/hubble
@@ -165,6 +167,7 @@ bin/start-hubble.sh -d
<img src="/docs/images/images-hubble/311图创建2.png" alt="image">
</div>
+> **注意**：如果使用 docker 启动 `hubble`，且 `server` 和 `hubble` 位于同一宿主机，不能直接使用
`localhost/127.0.0.1` 作为主机名。如果 `hubble` 和 `server` 在同一 docker 网络下，则可以直接使用
container_name 作为主机名，端口则为 8080。或者也可以使用宿主机 ip 作为主机名，此时端口为宿主机为 server 配置的端口
##### 4.1.2 图访问
实现图空间的信息访问，进入后，可进行图的多维查询分析、元数据管理、数据导入、算法分析等操作。
@@ -296,6 +299,9 @@ bin/start-hubble.sh -d
展示顶点类型和边类型的顶点索引和边索引。
#### 4.3 数据导入
+
+> **注意**：目前推荐使用 [hugegraph-loader](/cn/docs/quickstart/hugegraph-loader)
进行正式数据导入, hubble 内置的导入用来做**测试**和**简单上手**
+
数据导入的使用流程如下：
<center>
diff --git a/content/cn/docs/quickstart/hugegraph-server.md
b/content/cn/docs/quickstart/hugegraph-server.md
index b7ceea71..7e434395 100644
--- a/content/cn/docs/quickstart/hugegraph-server.md
+++ b/content/cn/docs/quickstart/hugegraph-server.md
@@ -42,19 +42,20 @@ java -version
可选项：
1. 可以使用 `docker exec -it graph bash` 进入容器完成一些操作
-2. 可以使用 `docker run -itd --name=graph -p 8080:8080 -e PRELOAD="true"
hugegraph/hugegraph` 在启动的时候预加载一个 **内置的**样例图。
+2. 可以使用 `docker run -itd --name=graph -p 8080:8080 -e PRELOAD="true"
hugegraph/hugegraph` 在启动的时候预加载一个**内置的**样例图。可以通过 `RESTful API` 进行验证。具体步骤可以参考
[5.1.1](/cn/docs/quickstart/hugegraph-server/#511-%E5%90%AF%E5%8A%A8-server-%E7%9A%84%E6%97%B6%E5%80%99%E5%88%9B%E5%BB%BA%E7%A4%BA%E4%BE%8B%E5%9B%BE)
-另外，我们也可以使用 `docker-compose`完成部署，使用用 `docker-compose up -d`, 以下是一个样例的
`docker-compose.yml`:
+另外，如果我们希望能够在一个文件中管理除了 `server` 之外的其他 Hugegraph 相关的实例，我们也可以使用
`docker-compose`完成部署，使用命令 `docker-compose up -d`，（当然只配置 `server` 也是可以的）以下是一个样例的
`docker-compose.yml`:
```yaml
version: '3'
services:
graph:
image: hugegraph/hugegraph
- #environment:
+ # environment:
# - PRELOAD=true
+ # PRELOAD 为可选参数，为 True 时可以在启动的时候预加载一个内置的样例图
ports:
- - 18080:8080
+ - 8080:8080
```
#### 3.2 下载 tar 包
@@ -142,7 +143,7 @@ bin/hugegraph deploy -v {hugegraph-version} -p
{install-path} [-u {download-path
#### 5.1 使用 Docker
-在 [3.1 使用 Docker 容器](#31-使用-docker-容器-推荐)中，我们已经介绍了 如何使用 `docker` 部署
`hugegraph-server`, 我们还可以设置参数在 sever 启动的时候加载样例图
+在 [3.1 使用 Docker 容器](#31-使用-docker-容器-推荐)中，我们已经介绍了如何使用 `docker` 部署
`hugegraph-server`, 我们还可以设置参数在 sever 启动的时候加载样例图
##### 5.1.1 启动 server 的时候创建示例图
@@ -150,11 +151,11 @@ bin/hugegraph deploy -v {hugegraph-version} -p
{install-path} [-u {download-path
1. 使用`docker run`
- 使用 `docker run -itd --name=graph -p 18080:8080 -e PRELOAD=true
hugegraph/hugegraph:latest`
+ 使用 `docker run -itd --name=graph -p 8080:8080 -e PRELOAD=true
hugegraph/hugegraph:latest`
2. 使用`docker-compose`
- 创建`docker-compose.yml`，具体文件如下
+ 创建`docker-compose.yml`，具体文件如下，在环境变量中设置
PRELOAD=true。其中，[`example.groovy`](https://github.com/apache/incubator-hugegraph/blob/master/hugegraph-dist/src/assembly/static/scripts/example.groovy)
是一个预定义的脚本，用于预加载样例数据。如果有需要，可以通过挂载新的 `example.groovy` 脚本改变预加载的数据。
```yaml
version: '3'
@@ -164,8 +165,10 @@ bin/hugegraph deploy -v {hugegraph-version} -p
{install-path} [-u {download-path
container_name: graph
environment:
- PRELOAD=true
+ volumes:
+ - /path/to/yourscript:/hugegraph/scripts/example.groovy
ports:
- - 18080:8080
+ - 8080:8080
```
使用命令 `docker-compose up -d` 启动容器
@@ -173,7 +176,7 @@ bin/hugegraph deploy -v {hugegraph-version} -p
{install-path} [-u {download-path
使用 RESTful API 请求 `HugeGraphServer` 得到如下结果：
```javascript
-> curl "http://localhost:18080/graphs/hugegraph/graph/vertices"; | gunzip
+> curl "http://localhost:8080/graphs/hugegraph/graph/vertices"; | gunzip
{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properti
[...]
```
@@ -210,7 +213,7 @@ rocksdb.data_path=.
rocksdb.wal_path=.
```
-初始化数据库（仅第一次启动时需要）
+初始化数据库（第一次启动时或在 `conf/graphs/` 下手动添加了新配置时需要进行初始化）
```bash
cd *hugegraph-${version}
@@ -252,7 +255,7 @@ hbase.port=2181
#hbase.edge_partitions=30
```
-初始化数据库（仅第一次启动时需要）
+初始化数据库（第一次启动时或在 `conf/graphs/` 下手动添加了新配置时需要进行初始化）
```bash
cd *hugegraph-${version}
@@ -298,7 +301,7 @@ jdbc.reconnect_interval=3
jdbc.ssl_mode=false
```
-初始化数据库（仅第一次启动时需要）
+初始化数据库（第一次启动时或在 `conf/graphs/` 下手动添加了新配置时需要进行初始化）
```bash
cd *hugegraph-${version}
@@ -340,7 +343,7 @@ cassandra.password=
#cassandra.keyspace.replication=3
```
-初始化数据库（仅第一次启动时需要）
+初始化数据库（第一次启动时或在 `conf/graphs/` 下手动添加了新配置时需要进行初始化）
```bash
cd *hugegraph-${version}
@@ -427,7 +430,7 @@ cassandra.password=
由于 scylladb 数据库本身就是基于 cassandra 的"优化版"，如果用户未安装 scylladb，也可以直接使用 cassandra
作为后端存储，只需要把 backend 和 serializer 修改为 scylladb，host 和 post 指向 cassandra 集群的
seeds 和 port 即可，但是并不建议这样做，这样发挥不出 scylladb 本身的优势了。
-初始化数据库（仅第一次启动时需要）
+初始化数据库（第一次启动时或在 `conf/graphs/` 下手动添加了新配置时需要进行初始化）
```bash
cd *hugegraph-${version}
@@ -569,7 +572,15 @@ _说明_
}
```
-详细的 API 请参考 [RESTful-API](/docs/clients/restful-api) 文档
+<p id="swaggerui-example"></p>
+
+详细的 API 请参考 [RESTful-API](/docs/clients/restful-api) 文档。
+
+另外也可以通过访问 `localhost:8080/swagger-ui/index.html` 查看 API。
+
+<div style="text-align: center;">
+ <img src="/docs/images/images-server/621swaggerui示例.png" alt="image">
+</div>
### 7 停止 Server
diff --git a/content/en/docs/clients/restful-api/_index.md
b/content/en/docs/clients/restful-api/_index.md
index 9265a345..8c353852 100644
--- a/content/en/docs/clients/restful-api/_index.md
+++ b/content/en/docs/clients/restful-api/_index.md
@@ -4,7 +4,9 @@ linkTitle: "RESTful API"
weight: 1
---
-HugeGraph-Server provides interfaces for clients to operate on graphs based on
the HTTP protocol through the HugeGraph-API. These interfaces primarily include
the ability to add, delete, modify, and query metadata and graph data, perform
traversal algorithms, handle variables, and perform other graph-related
operations.
+HugeGraph-Server provides interfaces for clients to operate on graphs based on
the HTTP protocol through the HugeGraph-API. These interfaces primarily include
the ability to add, delete, modify, and query metadata and graph data, perform
traversal algorithms, handle variables, and perform other graph-related
operations.
+
+Expect the doc below, you can also use `swagger-ui` to visit the `RESTful API`
by `localhost:8080/swagger-ui/index.html`. [Here is an
example](/docs/quickstart/hugegraph-server#swaggerui-example)
[comment]: <> (- Graph Schema)
diff --git a/content/en/docs/config/config-guide.md
b/content/en/docs/config/config-guide.md
index 3d826fcd..f335bf99 100644
--- a/content/en/docs/config/config-guide.md
+++ b/content/en/docs/config/config-guide.md
@@ -349,7 +349,7 @@ Initialization finished.
$ ./bin/start-hugegraph.sh
Starting HugeGraphServer...
-Connecting to HugeGraphServer (http://127.0.0.1:18080/graphs)...OK
+Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)...OK
Started [pid 21614]
```
diff --git
"a/content/en/docs/images/images-server/621swaggerui\347\244\272\344\276\213.png"
"b/content/en/docs/images/images-server/621swaggerui\347\244\272\344\276\213.png"
new file mode 100644
index 00000000..87a15481
Binary files /dev/null and
"b/content/en/docs/images/images-server/621swaggerui\347\244\272\344\276\213.png"
differ
diff --git a/content/en/docs/quickstart/hugegraph-hubble.md
b/content/en/docs/quickstart/hugegraph-hubble.md
index 48072901..29576877 100644
--- a/content/en/docs/quickstart/hugegraph-hubble.md
+++ b/content/en/docs/quickstart/hugegraph-hubble.md
@@ -41,7 +41,9 @@ There are three ways to deplot `hugegraph-hubble`
#### 2.1 Use docker (recommended)
-> **Special Note**: If you are starting `hubble` with Docker, and `hubble` and
the server are on the same host. When configuring the hostname for the graph on
the Hubble web page, please do not directly set it to `localhost/127.0.0.1`.
This will refer to the `hubble` container internally rather than the host
machine, resulting in a connection failure to the server. If `hubble` and
`server` is in the same docker network, you can use the `container_name` as the
hostname, and `8080` as the [...]
+> **Special Note**: If you are starting `hubble` with Docker, and `hubble` and
the server are on the same host. When configuring the hostname for the graph on
the Hubble web page, please do not directly set it to `localhost/127.0.0.1`.
This will refer to the `hubble` container internally rather than the host
machine, resulting in a connection failure to the server.
+>
+> If `hubble` and `server` is in the same docker network, we **recommend**
using the `container_name` (in our example, it is `graph`) as the hostname, and
`8080` as the port. Or you can use the **host IP** as the hostname, and the
port is configured by the host for the server.
We can use `docker run -itd --name=hubble -p 8088:8088 hugegraph/hubble` to
quick start [hubble](https://hub.docker.com/r/hugegraph/hubble).
@@ -56,7 +58,7 @@ services:
image: hugegraph/hugegraph
container_name: graph
ports:
- - 18080:8080
+ - 8080:8080
hubble:
image: hugegraph/hubble
@@ -160,12 +162,13 @@ Under the graph management module, click [Create graph],
and realize the connect
</div>
-Create graph by filling in the content as follows:：
+Create graph by filling in the content as follows:
<center>
<img src="/docs/images/images-hubble/311图创建2.png" alt="image">
</center>
+> **Special Note**: If you are starting `hubble` with Docker, and `hubble` and
the server are on the same host. When configuring the hostname for the graph on
the Hubble web page, please do not directly set it to `localhost/127.0.0.1`. If
`hubble` and `server` is in the same docker network, we **recommend** using the
`container_name` (in our example, it is `graph`) as the hostname, and `8080` as
the port. Or you can use the **host IP** as the hostname, and the port is
configured by the h [...]
##### 4.1.2 Graph Access
Realize the information access of the graph space. After entering, you can
perform operations such as multidimensional query analysis, metadata
management, data import, and algorithm analysis of the graph.
@@ -275,7 +278,7 @@ List mode:
</center>
-Graph mode：
+Graph mode:
<center>
<img src="/docs/images/images-hubble/3241边创建2.png" alt="image">
@@ -295,6 +298,9 @@ Graph mode：
Displays vertex and edge indices for vertex types and edge types.
#### 4.3 Data Import
+
+> **Note**：currently, we recommend to use
[hugegraph-loader](/en/docs/quickstart/hugegraph-loader) to import data
formally. The built-in import of `hubble` is used for **testing** and **getting
started**.
+
The usage process of data import is as follows:
<center>
diff --git a/content/en/docs/quickstart/hugegraph-server.md
b/content/en/docs/quickstart/hugegraph-server.md
index 8e71a6ab..7cd4cc0f 100644
--- a/content/en/docs/quickstart/hugegraph-server.md
+++ b/content/en/docs/quickstart/hugegraph-server.md
@@ -37,19 +37,20 @@ We can use `docker run -itd --name=graph -p 8080:8080
hugegraph/hugegraph` to qu
Optional:
1. use `docker exec -it graph bash` to enter the container to do some
operations.
-2. use `docker run -itd --name=graph -p 8080:8080 -e PRELOAD="true"
hugegraph/hugegraph` to start with a **built-in** example graph.
+2. use `docker run -itd --name=graph -p 8080:8080 -e PRELOAD="true"
hugegraph/hugegraph` to start with a **built-in** example graph. We can use
`RESTful API` to verify the result. The detailed step can refer to
[5.1.1](http://127.0.0.1:1313/docs/quickstart/hugegraph-server/#511-create-example-graph-when-starting-server)
-Also, we can use `docker-compose` to deploy, with `docker-compose up -d`. Here
is an example `docker-compose.yml`:
+Also, if we want to manage the other Hugegraph related instances in one file,
we can use `docker-compose` to deploy, with the command `docker-compose up -d`
(you can config only `server`). Here is an example `docker-compose.yml`:
```yaml
version: '3'
services:
graph:
image: hugegraph/hugegraph
- #environment:
+ # environment:
# - PRELOAD=true
+ # PRELOAD is a option to preload a build-in sample graph when initializing.
ports:
- - 18080:8080
+ - 8080:8080
```
#### 3.2 Download the binary tar tarball
@@ -162,11 +163,11 @@ Set the environment variable `PRELOAD=true` when starting
Docker in order to loa
1. Use `docker run`
- Use `docker run -itd --name=graph -p 18080:8080 -e PRELOAD=true
hugegraph/hugegraph:latest`
+ Use `docker run -itd --name=graph -p 8080:8080 -e PRELOAD=true
hugegraph/hugegraph:latest`
2. Use `docker-compose`
- Create `docker-compose.yml` as following
+ Create `docker-compose.yml` as following. We should set the environment
variable `PRELOAD=true`.
[`example.groovy`](https://github.com/apache/incubator-hugegraph/blob/master/hugegraph-dist/src/assembly/static/scripts/example.groovy)
is a predefined script to preload the sample data. If needed, we can mount a
new `example.groovy` to change the preload data.
```yaml
version: '3'
@@ -177,7 +178,7 @@ Set the environment variable `PRELOAD=true` when starting
Docker in order to loa
environment:
- PRELOAD=true
ports:
- - 18080:8080
+ - 8080:8080
```
Use `docker-compose up -d` to start the container
@@ -246,7 +247,7 @@ rocksdb.data_path=.
rocksdb.wal_path=.
```
-Initialize the database (required only on first startup)
+Initialize the database (required on first startup or a new configuration was
manually added under 'conf/graphs/')
```bash
cd *hugegraph-${version}
@@ -288,7 +289,7 @@ cassandra.password=
#cassandra.keyspace.replication=3
```
-Initialize the database (required only on first startup)
+Initialize the database (required on first startup or a new configuration was
manually added under 'conf/graphs/')
```bash
@@ -350,7 +351,7 @@ cassandra.password=
Since the scylladb database itself is an "optimized version" based on
cassandra, if the user does not have scylladb installed, they can also use
cassandra as the backend storage directly. They only need to change the backend
and serializer to scylladb, and the host and post point to the seeds and port
of the cassandra cluster. Yes, but it is not recommended to do so, it will not
take advantage of scylladb itself.
-Initialize the database (required only on first startup)
+Initialize the database (required on first startup or a new configuration was
manually added under 'conf/graphs/')
```bash
cd *hugegraph-${version}
@@ -390,7 +391,7 @@ hbase.port=2181
#hbase.edge_partitions=30
```
-Initialize the database (required only on first startup)
+Initialize the database (required on first startup or a new configuration was
manually added under 'conf/graphs/')
```bash
cd *hugegraph-${version}
@@ -436,7 +437,7 @@ jdbc.reconnect_interval=3
jdbc.ssl_mode=false
```
-Initialize the database (required only on first startup)
+Initialize the database (required on first startup or a new configuration was
manually added under 'conf/graphs/')
```bash
cd *hugegraph-${version}
@@ -578,8 +579,16 @@ response body:
}
```
+<p id="swaggerui-example"></p>
+
For detailed API, please refer to [RESTful-API](/docs/clients/restful-api)
+You can also visit `localhost:8080/swagger-ui/index.html` to check the API.
+
+<div style="text-align: center;">
+ <img src="/docs/images/images-server/621swaggerui示例.png" alt="image">
+</div>
+
### 7 Stop Server
```bash
