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]>
apache · Nov 1, 2023 · 6210154 · 6210154
1 parent 828e867
commit 6210154
Show file tree

Hide file tree

Showing 10 changed files with 72 additions and 36 deletions.
diff --git 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]&#40;restful-api/schema.md&#41;)

diff --git 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示例.png b/content/cn/docs/images/images-server/621swaggerui示例.png
diff --git 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
@@ -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,19 +143,19 @@ 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 的时候创建示例图
 
 在 docker 启动的时候设置环境变量 `PRELOAD=true`, 从而实现启动脚本的时候加载数据。
 
 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,16 +165,18 @@ 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` 启动容器
 
 使用 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","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}
 ```
@@ -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
@@ -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
@@ -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示例.png b/content/en/docs/images/images-server/621swaggerui示例.png
diff --git 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 port. Or you can use the ip of the host as the hostname, and the port is configured by the host for the server.
+> **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 host for the server.
 
 ##### 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
@@ -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