This is an automated email from the ASF dual-hosted git repository.
ningjiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-website.git
commit c60effe66c89c0ba694522c679c0e09940bfa39f
Author: chinx <c54948...@126.com>
AuthorDate: Mon Nov 18 16:40:33 2019 +0800
Add an English getting-started for service center, toolbox, and syncer to
the website
---
_data/navigation.yml | 30 +-
_docs/getting-started.md | 27 ++
_pages/home.md | 2 +-
_service-center/install.md | 135 +++++++++
_service-center/registration-discovery.md | 121 +++++++++
_syncer/multi-servicecenters.md | 235 ++++++++++++++++
_syncer/quick-start.md | 105 +++++++
_toolkit/oas-validator.md | 436 ++++++++++++++++++++++++++++++
_toolkit/quick-start.md | 238 ++++++++++++++++
9 files changed, 1322 insertions(+), 7 deletions(-)
diff --git a/_data/navigation.yml b/_data/navigation.yml
index 2bdf117..c4ac147 100755
--- a/_data/navigation.yml
+++ b/_data/navigation.yml
@@ -13,7 +13,7 @@ t:
group: "users"
children:
- title: "Get started"
- url: /docs/quick-start/
+ url: /docs/getting-started/
group: "users"
- title: "Docs"
url: /docs/users/
@@ -35,8 +35,15 @@ t:
group: "release"
docs:
+ - title: "Getting Started"
+ url: /docs/getting-started/
+ - title: "Service Center"
+ children:
+ - title: "Install"
+ url: /docs/service-center/install/
+ - title: "Registration&Discovery"
+ url: /docs/service-center/registration-discovery/
- title: "Development of microservices application based on java
microservice SDK"
- url: /docs/quick-start/
children:
- title: "Get started"
url: /docs/quick-start/
@@ -53,7 +60,6 @@ t:
- title: Distributed Tracing
url: /docs/quick-start-advance/distributed-tracing/
- title: "Use mersher to merge into the servicecomb microservice system"
- url: /docs/mersher-quick-start/
children:
- title: "Get started"
url: /docs/mersher-quick-start/
@@ -67,6 +73,18 @@ t:
url: /docs/mersher-quick-start-advance/mersher-service-management/
- title: "Mersher Distributed Tracing"
url: /docs/mersher-quick-start-advance/mersher-distributed-tracing/
+ - title: "A contract-based microservice development toolkit"
+ children:
+ - title: "Quick Start"
+ url: /docs/toolkit/quick-start/
+ - title: "OpenAPI V3 Spec validation tools"
+ url: /docs/toolkit/oas-validator/
+ - title: "A multiple servicecenters synchronization tool"
+ children:
+ - title: "Quick Start"
+ url: /docs/syncer/quick-start/
+ - title: "Different service centers communicate with each other"
+ url: /docs/syncer/multi-servicecenters/
users:
- title: Java Chassis User Guide
children:
@@ -184,7 +202,7 @@ t:
group: "users"
children:
- title: "入门指南"
- url: /cn/docs/getting-started/
+ url: /cn/docs/quick-start/
group: "users"
- title: "用户手册"
url: /cn/docs/users/
@@ -214,7 +232,7 @@ t:
url: /cn/docs/service-center/install/
- title: "服务注册发现"
url: /cn/docs/service-center/registration-discovery/
- - title: "基于java微服务SDK开发微服务应用"
+ - title: "基于java微服务SDK开发微服务应用"
children:
- title: "入门指南"
url: /cn/docs/quick-start/
@@ -230,7 +248,7 @@ t:
url: /cn/docs/quick-start-advance/service-management/
- title: "分布式调用链追踪"
url: /cn/docs/quick-start-advance/distributed-tracing/
- - title: "使用mersher接入servicecomb微服务体系"
+ - title: "使用mersher接入servicecomb微服务体系"
children:
- title: "入门指南"
url: /cn/docs/mersher-quick-start/
diff --git a/_docs/getting-started.md b/_docs/getting-started.md
new file mode 100644
index 0000000..a5d6e0a
--- /dev/null
+++ b/_docs/getting-started.md
@@ -0,0 +1,27 @@
+---
+title: "Getting Started"
+lang: en
+ref: getting-started
+permalink: /docs/getting-started/
+excerpt: "ServiceComb Getting Started"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## Getting Started
+Apache ServiceComb is an open source solution for microservices. It consists
of multiple components that can be flexibly adapted to different scenarios
through the combination of components. This guide can help you get started
quickly with Apache ServiceComb, which is the best place to start trying for
first-time users.
+1. Download [the ServiceComb release](/release/)component
+2. [Install service-center](/docs/service-center/install/)
+3. [Registration&Discovery](/docs/service-center/registration-discovery/)
+4. Select the quick start instructions for the appropriate development
language to use.
+- [Development of microservices application based on java microservice
SDK](/docs/quick-start/)
+- [Use mersher to merge into the servicecomb microservice
system](/docs/mersher-quick-start/)
+5. If the project involves multi-party collaboration, or legacy systems want
to transform into microservices
+[A contract-based microservice development toolkit](/docs/toolkit/quick-start/)
+
+## Advanced
+1. [A multiple servicecenters synchronization tool](/docs/syncer/quick-start/)
+
+## More
+After completing the above, you can learn in depth through each service user
manual:
+[ServiceComb User Manual](/docs/users/)
diff --git a/_pages/home.md b/_pages/home.md
index 84c386e..66805bf 100755
--- a/_pages/home.md
+++ b/_pages/home.md
@@ -12,7 +12,7 @@ excerpt: 'Open-Source, Full-Stack Microservice Solution.With
out of the box, hig
<a href="/release" class="home-button btn--info">Download</a>
</div>
<div class="button-group def-inline-block">
- <a href="/docs/quick-start/" class="home-button btn--info">Get started</a>
+ <a href="/docs/getting-started/" class="home-button btn--info">Get
started</a>
</div>'
intro:
diff --git a/_service-center/install.md b/_service-center/install.md
new file mode 100644
index 0000000..47c9fed
--- /dev/null
+++ b/_service-center/install.md
@@ -0,0 +1,135 @@
+---
+title: "Install of ServiceCenter"
+lang: en
+ref: install
+permalink: /docs/service-center/install/
+excerpt: "Learn how to run ServiceComb's service center"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## Service-Center
+ServiceCenter is a service registry. The service provider can register its own
instance information to the ServiceCenter for the service consumer to discover
and use.
+
+## Run with release package
+1. Download [the latest release package of
Service-Center](/release/service-center-downloads/)
+ This example uses
apache-servicecomb-service-center-1.3.0-linux-amd64.tar.gz
+2. Start service-center
+ ```bash
+ # Decompression the package
+ $ tar -zxvf apache-servicecomb-service-center-1.3.0-linux-amd64.tar.gz
+
+ # Start the service of servicecenter
+ $ cd apache-servicecomb-service-center-1.3.0-linux-amd64/
+ $ ./start-service-center.sh
+ ```
+3. View service status
+ ```bash
+ # View process status
+ $ ps -ef | grep service-center
+ root 27048 1 2 14:38 pts/2 00:00:00 ./service-center
+ root 27164 22742 0 14:38 pts/2 00:00:00 grep --color=auto
service-center
+
+ # View the listening port
+ $ netstat -apn | grep :30100
+ tcp 0 0 127.0.0.1:30100 0.0.0.0:* LISTEN
27048/service-cente
+
+ # Call the interface with the curl command
+ $ curl http://127.0.0.1:30100
+
{"_links":{"pb:latest-pact-versions":{"href":"http://127.0.0.1:30100/pacts/latest","title":"Latest
pact
versions"},"pb:latest-provider-pacts":{"href":"http://127.0.0.1:30100/pacts/provider/{provider}/latest","title":"Latest
pacts by
provider","templated":true},"pb:latest-provider-pacts-with-tag":{"href":"http://127.0.0.1:30100/pacts/provider/{provider}/latest/{tag}","title":"Latest
pacts by provider with a specified
tag","templated":true},"pb:pacticipants":{"href":"http://127.0.0.1:30 [...]
+
+ # If the above content is returned, the startup was successful.
+ ```
+4. Start the website of frontend and view the status
+ ```bash
+ $ ./start-frontend.sh
+ $ ps -ef | grep frontend
+ root 1875 32096 0 17:43 pts/6 00:00:00 grep --color=auto frontend
+ root 3020 1 0 Nov05 ? 00:00:23 ./frontend
+
+ # View the listening port
+ $ netstat -apn | grep :30103
+ tcp 0 0 127.0.0.1:30103 0.0.0.0:* LISTEN
3020/frontend
+ ```
+5. Open the website page "http://127.0.0.1:30103"; with a browser, and view
instances of the service center in website.（The result is success if like this）
+ 
+ **_Warning_**
+ - If the frontend service is started not locally, it cannot be accessed
through http://127.0.0.1:30103; you need to modify the "frontend_host_ip" in
the configuration file as the host IP ，and open the website to accessed
http://{ip}:30103
+ - If Service-Center needs to provide external services, you need to modify
"httpaddr", and external applications use http://{ip}:30100 for access.
+ Like this：
+ 
+
+## Run with docker
+1. Download and run docker image
+ ```bash
+ # Download the docker image
+ $ docker pull servicecomb/service-center
+ # Start docker container
+ $ docker run -d -p 30100:30100 servicecomb/service-center
+ ```
+2. View container status and listening port
+ ```bash
+ $ docker ps | grep service-center
+ 0733021cd96d servicecomb/service-center
"/opt/service-cent..." 3 minutes ago Up 3 minutes
0.0.0.0:30100->30100/tcp gallant_varahamihira
+ ```
+
+## Deployment with Kubernetes
+1. Configuring the deployment of kubernetes
+ ```bash
+ $ cat <<EOF >> ./service-center.yaml
+ apiVersion: v1
+ kind: Service
+ metadata:
+ name: servicecenter
+ labels:
+ app: servicecenter
+ spec:
+ ports:
+ - port: 30100
+ name: http
+ selector:
+ app: servicecenter
+ ---
+ apiVersion: extensions/v1beta1
+ kind: Deployment
+ metadata:
+ name: servicecenter
+ spec:
+ replicas: 1
+ template:
+ metadata:
+ labels:
+ app: servicecenter
+ version: v1
+ spec:
+ containers:
+ - name: servicecenter
+ image: servicecomb/service-center:latest
+ imagePullPolicy: IfNotPresent
+ ports:
+ - containerPort: 30100
+ EOF
+ ```
+2. Deployment
+ ```bash
+ # create namespace "servicecomb"
+ $ kubectl create namespace servicecomb
+
+ # deploy service-center
+ $ kubectl -n servicecomb create -f service-center.yaml
+ ```
+3. View Pod status and Service port
+ ```bash
+ # View Pod status
+ $ kubectl -n servicecomb get pod
+ NAME READY STATUS RESTARTS AGE
+ servicecenter-7d964b7644-h6f4s 1/1 Running 0 72s
+
+ # View the the listening port of service
+ $ kubectl -n servicecomb get service
+ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+ servicecenter ClusterIP 10.104.241.163 <none> 30100/TCP 118s
+
+ $ curl http://10.104.241.163:30100
+ ...
+ ```
diff --git a/_service-center/registration-discovery.md
b/_service-center/registration-discovery.md
new file mode 100644
index 0000000..9f349c2
--- /dev/null
+++ b/_service-center/registration-discovery.md
@@ -0,0 +1,121 @@
+---
+title: "Registration&Discovery"
+lang: en
+ref: registration-discovery
+permalink: /docs/service-center/registration-discovery/
+excerpt: "Registration and discovery of the service-center"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## Registration&Discovery
+ In a microservices architecture, an application consists of a set of
services with a single responsibility, and each service is dynamically deployed
to a different node. How should we manage the dependencies between this set of
services?
+ 
+ The service registry has solved this problem. It allows the service of
provider to register its information to the service-center; the service of
consumer can discover the provider information from the service-center.
+ The service registry has several advantages:
+ - 1 Decouple the provider and the consumer, the service consumer does not
need to know the provider address;
+ - 2 Service dynamic discovery and scalability, dynamic changes of the
instance of provider will be pushed to the consumer with the service-center;
+ - 3 You can monitor the quality of service operations and service
dependencies dynamically, and provide governance capabilities for services.
+
+## Registration and discovery process
+ 
+ The service registration and discovery process in Service-Center has the
following steps:
+ - 1 Registration the provider service to Service-Center.
+ - 2 The provider sends a heartbeat to maintain the "UP" state in
Service-Center.
+ - 3 Registration the consumer service to Service-Center.
+ - 4 The Consumer discover the provider information from Service-Center.
+ - 5 The consumer request the provider and get results.
+
+The Service-Center registration and discovery interface is implemented based
on the RESTful standard. It is not restricted by the development language. For
the interface definition, please refer to [API
Document](https://rawcdn.githack.com/ServiceComb/service-center/master/docs/api-docs.html)
+
+## First used of registration and discovery
+This chapter is about how to implement the feature of micro-service discovery
with ServiceCenter.
+1. Registration the provider service
+ ```bash
+ $ curl -X POST \
+ http://127.0.0.1:30100/registry/v3/microservices \
+ -H 'content-type: application/json' \
+ -H 'x-domain-name: default' \
+ -d '{
+ "service":
+ {
+ "appId": "default",
+ "serviceName": "ProviderDemoService",
+ "version":"1.0.0"
+ }
+ }'
+ ```
+ And then you can get the 'ProviderDemoService' ID like below:
+ ```bash
+ {"serviceId":"fa82132706a6b75a13393d8cf48800f9689b2603"}
+ ```
+2. Registration the provider instance
+Mark down the micro-service ID and call the instance registration API,
according to the ServiceCenter definition: One process should be registered as
one instance.
+ ```bash
+ $ curl -X POST \
+
http://127.0.0.1:30100/registry/v3/microservices/fa82132706a6b75a13393d8cf48800f9689b2603/instances
\
+ -H 'content-type: application/json' \
+ -H 'x-domain-name: default' \
+ -d '{
+ "instance":
+ {
+ "hostName":"provider-demo",
+ "endpoints": [
+ "rest://127.0.0.1:8080"
+ ]
+ }
+ }'
+ ```
+ The successful response like below:
+ ```bash
+ {"instanceId":"6e160fb0196e11e9b8b50242ac110005"}
+ ```
+3. Registration the consumer service
+ ```bash
+ $ curl -X POST \
+ http://127.0.0.1:30100/registry/v3/microservices \
+ -H 'content-type: application/json' \
+ -H 'x-domain-name: default' \
+ -d '{
+ "service":
+ {
+ "appId": "default",
+ "serviceName": "ConsumerDemoService",
+ "version":"1.0.0"
+ }
+ }'
+ ```
+ if all are successful, it means you have completed the micro-service
registration and instance publish
+ ```bash
+ {"serviceId":"d08d29edbeaa372c5be88407aa9adb00b4cb6099"}
+ ```
+4. Discovery the provider
+The next step is that discovery the micro-service instance by service name and
version rule
+ ```bash
+ $ curl -X GET \
+
'http://127.0.0.1:30100/registry/v3/instances?appId=default&serviceName=ProviderDemoService&version=latest'
\
+ -H 'content-type: application/json' \
+ -H 'x-consumerid: d08d29edbeaa372c5be88407aa9adb00b4cb6099' \
+ -H 'x-domain-name: default'
+ {
+ "instances": [
+ {
+ "instanceId": "c23da577197111e9b8b50242ac110005",
+ "serviceId": "fa82132706a6b75a13393d8cf48800f9689b2603",
+ "endpoints": [
+ "rest://127.0.0.1:8080"
+ ],
+ "hostName": "provider-demo",
+ "status": "UP",
+ "healthCheck": {
+ "mode": "push",
+ "interval": 30,
+ "times": 3
+ },
+ "timestamp": "1547631199",
+ "modTimestamp": "1547631199",
+ "version": "1.0.0"
+ }
+ ]
+ }
+ ```
diff --git a/_syncer/multi-servicecenters.md b/_syncer/multi-servicecenters.md
new file mode 100644
index 0000000..8a519cf
--- /dev/null
+++ b/_syncer/multi-servicecenters.md
@@ -0,0 +1,235 @@
+---
+title: "Communication on differ-structure servicecenters"
+lang: cn
+ref: install
+permalink: /docs/syncer/multi-servicecenters/
+excerpt: "Learn how to use differ-structure, multi-service center
synchronization tool"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## ServiceCenter and Eureka
+
+Situation description：
+- EurekaServer： The Service-center of Eureka
+- AccountServer：The account server of register to Eureka
+- Servicecomb-ServiceCenter：Servicecomb-ServiceCenter
+- HelloServer：The server of register to Servicecomb-ServiceCenter，that
dependent on account server
+
+Instances cannot be discovered and accessed by each other between different
service centers, in a traditional environment. This will be easy to implement
when we use Syner. As shown below:
+
+
+### Operating environment
+ 1. 2 linux machines: （Host IP is like this：10.0.0.10 和 10.0.0.11）
+ 2. [JDK
1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
+ 3. [Maven 3.x](https://maven.apache.org/install.html)
+ 4. [Go 1.11.4](https://golang.google.cn/dl/)
+
+### Before starting：
+1. [Install ServiceCenter Release（>=1.3.0）](/docs/service-center/install/)
+```bash
+$ project_dir=`pwd`
+$ tar -zxvf apache-servicecomb-service-center-1.3.0-linux-amd64.tar.gz
+```
+2. Download [the
sample](https://github.com/apache/servicecomb-service-center/tree/master/syncer/samples/multi-servicecenters)
+```bash
+git clone https://github.com/apache/servicecomb-service-center.git
+cd ${project_dir}/servicecomb-service-center/syncer
+```
+
+### Step 1: Launch the Eureka environment and services
+One of the machines： 10.0.0.10
+#### 1. Compile EurekaServer and AccountServer
+```bash
+$ cd samples/multi-servicecenters/eureka
+$ mvn clean install
+```
+#### 2. Run EurekaServer：
+- Modify the startup configuration
+ File
path：${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/eureka/eureka-server/src/main/resources/application.yaml
+```yml
+spring:
+ application:
+ name: eureka-server
+server:
+ port : 8761
+# servlet:
+# context-path: /eureka
+eureka:
+ instance:
+ hostname : 10.0.0.10
+ client:
+ registerWithEureka : false
+ fetchRegistry : false
+ serviceUrl:
+ defaultZone : http://${eureka.instance.hostname}:${server.port}/eureka/
+management:
+ endpoints:
+ web:
+ exposure:
+ include: "*"
+```
+
+- Run server
+```bash
+$ cd
${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/eureka/eureka-server/
+$ nohup mvn spring-boot:run & >> eureka-server.log 2>&1 &
+```
+Open http://10.0.0.10:8761 in the browser, this is successful if the following
page appears.
+
+
+#### 3. Run AccountServer
+- Modify the startup configuration
+ File
path：${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/eureka/account-server/src/main/resources/application.yaml
+```yml
+spring:
+ application:
+ name: account-server
+server:
+ port: 8090
+eureka:
+ instance:
+ hostname: 10.0.0.10
+ client:
+ service-url:
+ defaultZone: http://${eureka.instance.hostname}:8761/eureka/
+management:
+ endpoints:
+ web:
+ exposure:
+ include: "*"
+```
+- Start AccountServer
+```bash
+$ cd
${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/eureka/account-server
+$ mvn spring-boot:run
+
+# This is successful if the result like this，
+2019-09-19 17:20:35.534 INFO 20890 --- [ main]
o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8090
(http) with context path ''
+2019-09-19 17:20:35.548 INFO 20890 --- [ main]
.s.c.n.e.s.EurekaAutoServiceRegistration : Updating port to 8090
+2019-09-19 17:20:35.551 INFO 20890 --- [ main]
o.a.s.s.account.AccountApplication : Started AccountApplication in 3.92
seconds (JVM running for 6.754)
+2019-09-19 17:20:35.617 INFO 20890 --- [nfoReplicator-0]
com.netflix.discovery.DiscoveryClient :
DiscoveryClient_ACCOUNT-SERVER/10.0.0.10:account-server:8090 - registration
status: 204
+```
+Reopen http://10.0.0.10:8761, you can see that AccountServer has been
registered successfully.
+
+
+#### 4. Run Syncer of eureka
+```bash
+$ cd ${project_dir}/apache-servicecomb-service-center-1.3.0-linux-amd64/
+$ ./syncer daemon --sc-addr http://10.0.0.10:8761/eureka --bind-addr
10.0.0.10:30190 --rpc-addr 10.0.0.10:30191 --sc-plugin=eureka --node eureka
+
+# This is successful if the result like this，
+2019-09-19T17:28:28.809+0800 INFO etcd/agent.go:55 start etcd
success
+2019-09-19T17:28:28.809+0800 INFO grpc/server.go:94 start grpc
success
+2019-09-19T17:28:28.809+0800 DEBUG server/handler.go:39 is leader: true
+2019-09-19T17:28:28.809+0800 DEBUG server/handler.go:43 Handle Tick
+```
+
+### Step 2: Start the Servicecenter environment and services
+Another machine： 10.0.0.11
+#### 1. Compile HelloServer
+```bash
+$ cd
${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/servicecenter/hello-server/
+$ GO111MODULE=on go build
+```
+#### 2. Run Servicecenter
+- Modify the startup configuration：
+ File
path：${project_dir}/apache-servicecomb-service-center-1.3.0-linux-amd64/conf/app.conf
+```conf
+frontend_host_ip = 10.0.0.11
+frontend_host_port = 30103
+
+###################################################################
+# sever options
+###################################################################
+# if you want to listen at ipv6 address, then set the httpaddr value like:
+# httpaddr = 2400:A480:AAAA:200::159 (global scope)
+# httpaddr = fe80::f816:3eff:fe17:c38b%eth0 (link-local scope)
+httpaddr = 10.0.0.11
+httpport = 30100
+# ...以下省略...
+```
+
+- Run ServiceCenter and Frontend
+```bash
+$ cd ${project_dir}/apache-servicecomb-service-center-1.3.0-linux-amd64
+$ ./start-service-center.sh
+$ ./start-frontend.sh
+```
+Open http://10.0.0.11:30103 in the browser, this is successful if the
following page appears.
+
+
+
+#### 3. Run HelloServer
+- Modify the startup configuration
+ File
path：${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/servicecenter/hello-server/conf/microservice.yaml
+```yml
+service: # Micro service configuration
+ appId: eureka # The appID is "eureka", if the instance synced from eureka.
+ name: hello-server
+ version: 0.0.1
+ instance: # Instance information
+ protocol: rest
+ listenAddress: 10.0.0.11:8091 #The listening address of the instance
+provider: # Provider information
+ appId: eureka
+ name: account-server
+ version: 0.0.1
+registry:
+ address: http://10.0.0.11:30100
+```
+
+- Start HelloServer
+```bash
+$ cd
${project_dir}/servicecomb-service-center/syncer/samples/multi-servicecenters/servicecenter/hello-server
+$ ./hello-server
+2019-09-19T18:37:50.645+0800 DEBUG servicecenter/servicecenter.go:163
send heartbeat success
+2019-09-19T18:37:50.645+0800 WARN servicecenter/servicecenter.go:85
discovery provider failed, appID = eureka, name = account-server, version =
0.0.1
+2019-09-19T18:37:50.645+0800 INFO servicecenter/servicecenter.go:87
waiting for retry
+```
+Reopen http://10.0.0.11:30103, you can see that HelloServer has been
registered successfully.
+
+
+But, the instance of AccountServer belonging to the EurekaServer cannot be
found, the HelloServer is in the retry state.
+(**_Warning_**: We must complete the operation within 3 retry times (90
seconds))
+
+#### 4.Run Syncer of service-center
+```bash
+$ cd ${project_dir}/apache-servicecomb-service-center-1.3.0-linux-amd64/
+$ ./syncer daemon --sc-addr http://10.0.0.11:30100 --bind-addr 10.0.0.11:30190
--rpc-addr 10.0.0.11:30191 --sc-plugin=servicecenter --join-addr
10.0.0.10:30190 --node servicecenter
+
+# This is successful if the result like this，
+2019-09-19T18:44:35.536+0800 DEBUG server/handler.go:62 is leader: true
+2019-09-19T18:44:35.536+0800 DEBUG server/handler.go:79 Receive serf
user event
+2019-09-19T18:44:35.536+0800 DEBUG serf/agent.go:130 member =
servicecenter, groupName = 0204d59328090c2f4449a088d4e0f1d8
+2019-09-19T18:44:35.536+0800 DEBUG serf/agent.go:130 member =
eureka, groupName = 34f53a9520a11c01f02f58f733e856b3
+2019-09-19T18:44:35.536+0800 DEBUG server/handler.go:97 Going to pull
data from eureka 10.0.0.10:30191
+2019-09-19T18:44:35.536+0800 INFO grpc/client.go:76 Create new grpc
connection to 10.0.0.10:30191
+2019-09-19T18:44:35.538+0800 DEBUG servicecenter/servicecenter.go:87
create service success orgServiceID= account-server, curServiceID =
80784229255ec96d90353e3c041bdf3586fdbbae
+2019-09-19T18:44:35.538+0800 DEBUG servicecenter/servicecenter.go:90
trying to do registration of instance, instanceID =
10.0.0.10:account-server:8090
+2019-09-19T18:44:35.540+0800 DEBUG servicecenter/sync.go:63
Registered instance successful, instanceID = 78bca3e2daca11e99638fa163eca30e0
+```
+
+### Step 3: Results Verification
+1. At this point, HelloServer gets the instance successfully, and calls the
CheckHealth interface of AccountServer.
+
+
+2. Open the website of Euraka and ServiceCenter respectively. Both service
centers contain all the instance information.
+
+
+3. Call the Login interface of HelloServer used the command line of curl,
+```bash
+$ curl -X POST \
+http://192.168.88.75:8091/login \
+-H 'Content-Type: application/json' \
+-d '{
+ "user":"Jack",
+ "password":"123456"
+}'
+welcome Jack
+```
+HelloServer and AccountServer respectively print the following information.
+AccountServer
+
+HelloServer
+
diff --git a/_syncer/quick-start.md b/_syncer/quick-start.md
new file mode 100644
index 0000000..3ef18c6
--- /dev/null
+++ b/_syncer/quick-start.md
@@ -0,0 +1,105 @@
+---
+title: "Syncer Quick Start"
+lang: en
+ref: install
+permalink: /docs/syncer/quick-start/
+excerpt: "Learn how to use differ-structure, multi-service center
synchronization tool"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## Differ-structure, multi-service center synchronization tool
+Syncer is a multiple servicecenters synchronization tool designed for large
microservice architectures,supporting differ-structure servicecenters.
+
+## Quick Start
+1 Getting & Running Service center
+
+Take Service-center as an example, reference to [Install
ServiceCenter](/docs/service-center/install/)
+
+2. Download and decompression
[ServiceCenter发布包（>=1.3.0）](/release/service-center-downloads/)
+```bash
+# 解压tar包
+$ tar -zxvf apache-servicecomb-service-center-1.3.0-linux-amd64.tar.gz
+$ cd apache-servicecomb-service-center-1.3.0-linux-amd64/
+```
+
+##### 3.3 Running ServiceCenter Syncer
+###### Parameter Description
+- node
+
+ The member name of syncer, that must be unique in the cluster
+
+- sc-addr
+
+ Service center address, which is the service registry address. Cluster mode
is supported, and multiple addresses are separated by commas.
+
+- bind-addr
+
+ P2P address of Syncer for communication with other Syner members in P2P
networks by Gossip.
+
+- rpc-addr
+
+ Address of Syncer for data transmission, used to synchronize microservices
data between Syncers.
+
+- join-addr
+
+ The bind-addr of target syncer, one of other syncer members, the current
Syncer will join the network by this.
+
+- mode
+
+ Runtime mode of Syncer, specify 'cluster' for cluster mode which enables
each Syncer to have three instance, default to 'single' mode.
+
+- cluster-name
+
+ Name of the Syncer cluster when mode is set to be 'cluster'.
+
+- cluster-port
+
+ The port that the Syner cluster members communicate with when mode is set to
be "cluster".
+
+Suppose there are 2 Service centers, each of them with a Service-center
cluster for microservices discovery and registry, as following,
+
+| Servicecenter | Local address |
+| :--------------------: | :-----------: |
+| http://10.0.0.10:30100 | 10.0.0.10 |
+| http://10.0.0.11:30100 | 10.0.0.11 |
+
+#### Single Mode
+
+Start Service-center Syncer to enable communication between 2 service centers
+
+- Start Sycner on host 10.0.0.10
+
+```bash
+$ ./syncer daemon --sc-addr http://10.0.0.10:30100 --bind-addr 10.0.0.10:30190
--rpc-addr 10.0.0.10:30191
+```
+
+- Start Syncer on host 10.0.0.11 and join into 10.0.0.10 gossip pool
+
+```bash
+$ ./syncer daemon --sc-addr http://10.0.0.11:30100 --bind-addr 10.0.0.11:30190
--rpc-addr 10.0.0.11:30191 --join-addr 10.0.0.10:30191
+```
+
+#### Cluster Mode
+
+Start 2 Syncer clusters on there host to synchronize microservice data between
the 2 service centers
+
+- Start Syncer cluster on host 10.0.0.10
+
+```bash
+$ ./syncer daemon --sc-addr http://10.0.0.10:30100 --bind-addr 10.0.0.10:30190
--rpc-addr 10.0.0.10:30191 --mode cluster --node syncer011 --cluster-port 30201
--join-addr 10.0.0.10:30190
+$ ./syncer daemon --sc-addr http://10.0.0.10:30100 --bind-addr 10.0.0.10:30290
--rpc-addr 10.0.0.10:30291 --mode cluster --node syncer012 --cluster-port 30202
--join-addr 10.0.0.10:30190
+$ ./syncer daemon --sc-addr http://10.0.0.10:30100 --bind-addr 10.0.0.10:30390
--rpc-addr 10.0.0.10:30391 --mode cluster --node syncer013 --cluster-port 30203
--join-addr 10.0.0.10:30190
+```
+
+- Start Syncer cluster on host 10.0.0.11
+
+```bash
+$ ./syncer daemon --sc-addr http://10.0.0.11:30100 --bind-addr 10.0.0.11:30190
--rpc-addr 10.0.0.11:30191 --mode cluster --node syncer021 --cluster-port 30201
--join-addr 10.0.0.10:30190
+$ ./syncer daemon --sc-addr http://10.0.0.11:30100 --bind-addr 10.0.0.11:30290
--rpc-addr 10.0.0.11:30291 --mode cluster --node syncer022 --cluster-port 30202
--join-addr 10.0.0.10:30190
+$ ./syncer daemon --sc-addr http://10.0.0.11:30100 --bind-addr 10.0.0.11:30390
--rpc-addr 10.0.0.11:30391 --mode cluster --node syncer023 --cluster-port 30203
--join-addr 10.0.0.10:30190
+```
+
+**Verification**
+30 seconds after registering a microservice to one of the Service-centers,
the information about it can be get from the other one.
+
diff --git a/_toolkit/oas-validator.md b/_toolkit/oas-validator.md
new file mode 100644
index 0000000..dfe0b80
--- /dev/null
+++ b/_toolkit/oas-validator.md
@@ -0,0 +1,436 @@
+---
+title: "OpenAPI V3 Spec validation tools"
+lang: cn
+ref: install
+permalink: /docs/toolkit/oas-validator/
+excerpt: "Learn how to use OpenAPI V3 Spec validation tools"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## Project structure
+
+* oas-validator-core: core apis and skeletons implementations
+* oas-validator-core-spring: Spring Boot Starter for core skeletons
+* oas-validator-test: test helpers for core api
+* oas-validator-compliance: check style validators
+* oas-validator-compliance-spring: Spring Boot Starter for check style
validators
+* oas-validator-compatibility: compatibility validators
+* oas-validator-compatibility-spring: Spring Boot Starter for compatibility
validators
+* oas-validator-web: web ui
+
+## Style check rules
+
+OAS must compatible with [OAS 3.0.2][openapi-3.0.2], besides must obey the
following rules.
+
+### String patterns
+
+* <a name="lower-camel-case"></a> Lower Camel Case: initial letter lowercase
camel case, regex is `^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$`
+* <a name="upper-camel-case"></a> Upper Camel Case: initial letter uppercase
camel case, regex is `^[A-Z]([a-z0-9]+[A-Z]?)*$`
+* <a name="upper-hyphen-case"></a> Upper Hyphen Case: initial letter
uppercase, multiple words concat with `-`, such as `Content-Type`, `Accept`,
`X-Rate-Limit-Limit`, regex is `^([A-Z][a-z0-9]*-)*([A-Z][a-z0-9]*)$`
+
+### OpenAPI Object [doc][spec-openapi]
+
+<a name="openapi-compliance"></a>
+
+* `openapi` property must be 3.0.x and >= 3.0.2
+* `info` propety, see [Info Object style check rules](#info-compliance)
+* `paths` property, must provide, see [Paths Object style check
rules](#paths-compliance)
+* `components` property, see [Components Object style check
rules](#components-compliance)
+* `tags` property should at least provide one [Tag Object][spec-tag]
+ * see [Tag Object style check rules](#tag-compliance)
+* `security` property, should not provide
+
+### Info Object [doc][spec-info]
+
+<a name="info-compliance"></a>
+
+* `description` property, required
+
+### Tag Object [doc][spec-tag]
+
+<a name="tag-compliance"></a>
+
+- `name` property, must be [Upper Camel Case](#upper-camel-case)
+- `description` property, required
+- Every tag should be referenced by at least one [Operation
Object][spec-operation]
+
+### Paths Object [doc][spec-paths]
+
+<a name="paths-compliance"></a>
+
+* path must be [Lower Camel Case](#lower-camel-case), including [Path
Templating][spec-path-templating] variable
+ * see [Path Item Object style check rules](#path-item-compliance)
+
+### Path Item Object [doc][spec-path-item]
+
+<a name="path-item-compliance"></a>
+
+* `get/post/put/delete/...` properties, see [Operation Object style check
rules](operation-compliance)
+* `parameters` property, see [Parameter Object style check
rules](#parameter-compliance)
+
+### Operation Object [doc][spec-operation]
+
+<a name="operation-compliance"></a>
+
+* `summary` property, required
+* `operationId` property, must be [Lower Camel Case](#lower-camel-case)
+* `parameters` property, see [Parameter Object style check
rules](#parameter-compliance)
+* `requestBody` property, see [Request Body Object style check
rules](#request-body-compliance)
+* `responses` property, see [Responses Object style check
rules](#responses-compliance)
+* `tags` property, can only provide one tag, must be in the range of [OpenAPI
Object][spec-openapi] `tags` property
+* `servers` property, should not provide
+
+### Parameter Object [doc][spec-parameter]
+
+<a name="parameter-compliance"></a>
+
+* `description` property, required
+* `name` property
+ * if `in` is path, query or cookie, then must be [Lower Camel
Case](#lower-camel-case)
+ * if `in` is header, then must be [Upper Hyphen Case](#upper-hyphen-case)
+* `schema` property, see [Schema Object check sytle rules](#schema-compliance)
+* `content` property, see [Media Type Object style check
rules](#media-type-compliance)
+
+### Request Body Object [doc][spec-request-body]
+
+<a name="request-body-compliance"></a>
+
+* `description` property, required
+* `content` property, see [Media Type Object style check
rules](#media-type-compliance)
+
+### Media Type Object [doc][spec-media-type]
+
+<a name="media-type-compliance"></a>
+
+* `schema` property, required. See [Schema Object style check
rules](#schema-compliance)
+* `encoding` property, see [Encoding Object style check
rules](#encoding-compliance)
+
+### Responses Object [doc][spec-responses]
+
+<a name="responses-compliance"></a>
+
+* See [Response Object style check rules](#response-compliance)
+
+### Response Object [doc][spec-response]
+
+<a name="response-compliance"></a>
+
+* `description` property, required
+* `headers` property, name (`headers` key) must be [Upper Hyphen
Case](#upper-hyphen-case)
+ * See [Header Object style check rules](#header-compliance)
+* `content` property, see [Media Type Object style check
rules](#media-type-compliance)
+
+### Schema Object [doc][spec-schema]
+
+<a name="schema-compliance"></a>
+
+* `title` property, required if parent is [Schema Object][spec-schema] or
[Components Object][spec-components]
+* `properties` property, name(`properties` key) must be [Lower Camel
Case](#lower-camel-case)
+ * Sub Schema, see [Schema Object style check rules](#schema-compliance)
+
+### Encoding Object [doc][spec-encoding]
+
+<a name="encoding-compliance"></a>
+
+* `headers` property, name(`headers` key) must be [Upper Hyphen
Case](#upper-hyphen-case)
+ * See [Header Object style check rules](#header-compliance)
+
+### Header Object [doc][spec-header]
+
+<a name="header-compliance"></a>
+
+* `description` property, required
+* `schema` property, see [Schema Object style check rules](#schema-compliance)
+* `content` property, see [Media Type Object style check
rules](#media-type-compliance)
+
+### Components Object [doc][spec-components]
+
+<a name="components-compliance"></a>
+
+* `schemas` property, name must be [Upper Camel Case](#upper-camel-case)
+ * See [Schema Object style check rules](#schema-compliance)
+* `responses` property, name must be [Upper Camel Case](#upper-camel-case)
+ * See [Response Object style check rules](#response-compliance)
+* `parameters` property, name must be [Upper Camel Case](#upper-camel-case)
+ * See [Parameter Object style check rules](#parameter-compliance)
+* `examples` property, name must be [Upper Camel Case](#upper-camel-case)
+* `requestBodies` property, name must be [Upper Camel Case](#upper-camel-case)
+ * See [Request Body style check rules](#request-body-compliance)
+* `headers` property, name must be [Upper Hyphen Case](#upper-hyphen-case)
+ * See [Header style check rules](#header-compliance)
+* `links` property, name must be [Upper Camel Case](#upper-camel-case)
+* `callbacks` property, name must be [Upper Camel Case](#upper-camel-case)
+
+## Compatibility check rules
+
+Check whether new OAS spec compatibile with old spec.
+
+Notice: OAS could use [Reference Object][spec-reference], two OAS which are
different in text maybe semantically same. For example, below old OAS doesn't
use [Reference Object][spec-reference] while the new one uses:
+
+Old OAS
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: Swagger Petstore
+ license:
+ name: MIT
+servers:
+ - url: http://petstore.swagger.io/v1
+paths:
+ /pets:
+ post:
+ summary: List all pets
+ operationId: listPets
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ properties:
+ Foo:
+ type: string
+ responses:
+ '200':
+ description: A paged array of pets
+```
+
+New OAS
+
+```yaml
+paths:
+ /pets:
+ post:
+ operationId: listPets
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Foo'
+ responses:
+ '200':
+ description: A paged array of pets
+components:
+ schemas:
+ Foo:
+ type: array
+ items:
+ type: object
+ properties:
+ Foo:
+ type: string
+```
+
+So, when do compatibility check we resolve [Reference Object][spec-reference]
in old and new OAS first, then do the check, below is the code snippet using
[swagger-parser][swagger-parser]:
+
+```java
+OpenAPIV3Parser parser = new OpenAPIV3Parser();
+
+ParseOptions parseOptions = new ParseOptions();
+parseOptions.setResolve(true);
+parseOptions.setResolveCombinators(true);
+parseOptions.setResolveFully(true);
+parseOptions.setFlatten(false);
+
+SwaggerParseResult parseResult = parser.readContents(content, null,
parseOptions);
+```
+
+So if compatibility violations be found, the reported location will be
different from the location in origin OAS spec.
+
+### Paths Object [doc][spec-paths]
+
+<a name="paths-compatibility"></a>
+
+* New OAS must include all the `path` appears in 旧OAS. If `path` uses [Path
Templating][spec-path-templating], even the variable name changed, will be
considered semantically different. For example `/pets/{foo}` and `/pets/{bar}`
are different.
+ * See [Path Item Object compatibility check rules](#path-item-compatibility)
+
+### Path Item Object [doc][spec-path-item]
+
+<a name="path-item-compatibility"></a>
+
+* New OAS must inclued all old OAS get/put/post/delete/...[Operation
Object][spec-operation]
+
+### Operation Object [doc][spec-operation]
+
+<a name="operation-compatibility"></a>
+
+* `operationId` property, new and old must be identical
+* `parameters` property, check work must also consider [Path Item Object
parameters property][spec-path-item-parameters]:
+ * New OAS could add new [Parameter Object][spec-parameter], but the new
[Parameter Object][spec-parameter] `required` property must be `false`
+ * New OAS could delete[Parameter Object][spec-parameter]
+ * The check on [Parameter Object][spec-parameter] see [Parameter Object
compatibility check rules](#parameter-compatibility)(Under the same [Operation
Object][spec-operation] [Parameter Object][spec-parameter] is identified by
`name` and `in` property)。
+* `requestBody` property, see [Request Body Object compatibility check
rules](#request-body-compatibility)
+* `responses` property, see[Responses Object compatibility check
rules](#responses-compatibility)
+
+### Parameter Object [doc][spec-parameter]
+
+<a name="parameter-compatibility"></a>
+
+* `required` property, only allow `true(old) -> false(new)` change
+* `allowEmptyValue` property, only allow `false(old) -> true(new)` change
+* `style` property, new and old must be identical
+* `explode` property, new and old must be identical
+* `allowReserved` property, only allow `false(old) -> true(new)` change
+* `schema` property, see [Schema Object compatibility check
rules](#schema-compatibility)
+* `content`property, new OAS must include all old OAS media type (`content`
keys), and add new media type is not allowed
+ * see [Media Type Object compatibility check
rules](#media-type-compatibility)
+
+### Request Body Object [doc][spec-request-body]
+
+<a name="request-body-compatibility"></a>
+
+* `content`property, new OAS must include all old OAS media type (`content`
keys)
+ * See [Media Type Object compatibility check
rules](#media-type-compatibility)
+* `required` property, only allow `true(old) -> false(new)` change
+
+### Media Type Object [doc][spec-media-type]
+
+<a name="media-type-compatibility"></a>
+
+* `schema` property, see [Schema Object compatibility check
rules](#schema-compatibility)
+* `encoding` property, this property only apply to `requestBody`, so new OAS
and old OAS property name(`encoding` key) must be identical
+ * See [Encoding Object compatibility check rules](#encoding-compatibility)
+
+### Responses Object [doc][spec-responses]
+
+<a name="responses-compatibility"></a>
+
+* `default` property, if old OAS doesn't define `default`, then new OAS should
not define `default` too.
+* `{Http Status Code}` property, new OAS is not allowed to add one.
+* See [Response Object compatibility check rules](#response-compatibility)
+
+### Response Object [doc][spec-response]
+
+<a name="response-compatibility"></a>
+
+* `headers` property, new OAS must include all old OAS header name(`headers`
keys), and add new header name is allowed
+ * [Header Object][spec-header] see [Header Object compatibility check
rules](#header-compatibility)
+* `content` property, new OAS must include all old OAS media type(`content`
keys), and add new media type is allowed
+ - [Media Type Object][spec-media-type] see [Media Type Object compatibility
check rules](#media-type-compatibility)
+
+### Schema Object [doc][spec-schema]
+
+<a name="schema-compatibility"></a>
+
+OAS allows Schema Object be directly or indirectly in:
+
+* Request: [Parameter Object][spec-parameter], [Request Body
Object][spec-request-body], [Header Object][spec-header]
+* Response: [Header Object][spec-header], [Response Object][spec-response]
+
+In different context compatibility check rules are different.
+
+### In request context
+
+When Schema Object is in response context, only allow change from more
specific form to less specific form.
+
+* `type, format` combination allowed change:
+
+| Old (type,format) | New (type,format)
|
+| ---------------- |
------------------------------------------------------------ |
+| integer, null | integer, int64<br />number, double<br />number, null
|
+| integer, int32 | integer, int64<br />integer, null<br />number, float<br
/>number, double<br />number, null |
+| integer, int64 | integer, null<br />number, double<br />number, null
|
+| number, null | number, double
|
+| number, float | number, null<br />number, double
|
+| number, double | number, null
|
+| string, null | string, password
|
+| string, password | string, null
|
+
+* `allOf`, `oneOf`, `anyOf` property, combine them first then do check
+* `multipleOf` property, if old OAS is null, then new OAS must == old OAS or
new OAS is a factor of old OAS, eg, 6(old)->3(new)
+* `maximum`, `maxLength`, `maxItems`, `maxProperties`, if old OAS is null,
then new OAS must be null too. Otherwise, new OAS must be >= old OAS
+* `minimum`, `minLenght`, `minItems`, `minProperties`, if old OAS is null,
then new OAS must be null too. Otherwise, new OAS must be <= old OAS.
+* `exclusiveMaximum`, `exclusiveMinimum` property, only allow change
`true(old)->false(new)`
+* `uniqueItems` property, only allow change `true(old)->false(new)`
+* `required` property, new OAS must == old OAS or new OAS is old OAS subset
+* `enum` property, new OAS must == old OAS or new OAS is old OAS superset
+* `properties` property, new OAS could add or delete property
name(`properties` key)
+* `nullable` property, only allow change `false(old)->true(new)`
+* `discriminator` property, new and old must be identical
+* `xml` property, new and old must be identical
+* `readOnly`, `writeOnly` property, new and old must be identical
+
+### In response context
+
+When Schema Object is in response context, only allow change from less
specific form to more specific form.
+
+* `type, format` combination allowed change:
+
+| Old (type,format) | New (type,format) |
+| ---------------- | ---------------------------------- |
+| integer, null | integer, int64<br />integer, int32 |
+| integer, int64 | integer, null<br />interger, int32 |
+| number, null | number, double<br />number, float |
+| number, double | number, null<br />number, float |
+| string, null | string, password |
+| string, password | string, null |
+
+* `allOf`, `oneOf`, `anyOf` property, combine them first then do check
+* `multipleOf` property if old OAS is null. new OAS must == old OAS or new OAS
must be a multiple of old OAS, eg, 3(old)->6(new)
+* `maximum`, `maxLength`, `maxItems`, `maxProperties`, if old OAS is null,
then new OAS must be null too. Otherwise, new OAS must <= old OAS
+* `minimum`, `minLenght`, `minItems`, `minProperties`, if old OAS is null,
then new OAS must be null too. Otherwise, new OAS must >= old OAS
+* `exclusiveMaximum`, `exclusiveMinimum` property, only allow change
`false(old)->true(new)`
+* `uniqueItems` property, only allow change `false(old)->true(new)`
+* `required` new OAS must == old OAS or new OAS is old OAS superset
+* `enum` property, new OAS must == old OAS or new OAS is old OAS subset
+* `properties` property, new OAS could add or delete property
name(`properties` key)
+* `nullable` property , only allow change `true(old)->false(new)`
+* `discriminator` property, new and old must be identical
+* `xml` property, new and old must be identical
+* `readOnly`, `writeOnly` property, new and old must be identical
+
+### Encoding Object [doc][spec-encoding]
+
+<a name="encoding-compatibility"></a>
+
+Notice: Encoding Object only apply to Request Body Object
+
+* `contentType` property, new and old must be identical
+* `headers` property, new OAS can not add new he header name (`headers` key),
but and delete header name
+ * [Header Object][spec-header] see [Header Object compatibility check
rules](#header-compatibility)
+* `style` property, new and old must be identical
+* `explode` property, new and old must be identical
+* `allowReserved` property, only allow change `false(old) -> true(new)`
+
+### Header Object [doc][spec-header]
+
+<a name="header-compatibility"></a>
+
+- `schema` property, see [Schema Object compatibility check
rules](#schema-compatibility)
+
+### Components Object [doc][spec-components]
+
+<a name="components-compatibility"></a>
+
+[Components Object][spec-components] defines reusable OAS Object, but when
doing compatibility check all `$ref` are resolved, so no need to check
[Components Object][spec-components] compatibility.
+
+
+[spec-operation]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
+[openapi-3.0.2]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
+[spec-openapi]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object
+[spec-server]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
+[spec-info]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
+[spec-paths]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#paths-object
+[spec-path-item]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject
+[spec-parameter]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
+[spec-request-body]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject
+[spec-security-scheme]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject
+[spec-components]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#components-object
+[spec-tag]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#tagObject
+[spec-schema]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject
+
+[spec-media-type]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#media-type-object
+[spec-response]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#response-object
+[spec-path-templating]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-templating
+[spec-parameterIn]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterIn
+[spec-encoding]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#encodingObject
+[spec-header]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#header-object
+[spec-info]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
+[spec-reference]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#reference-object
+[swagger-parser]: https://github.com/swagger-api/swagger-parser
+[spec-path-item-parameters]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#user-content-pathitemparameters
+[spec-responses]:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject
diff --git a/_toolkit/quick-start.md b/_toolkit/quick-start.md
new file mode 100644
index 0000000..d90ebbf
--- /dev/null
+++ b/_toolkit/quick-start.md
@@ -0,0 +1,238 @@
+---
+title: "Toolkit Quick Start"
+lang: en
+ref: install
+permalink: /docs/toolkit/quick-start/
+excerpt: "Learn how to use toolkit"
+last_modified_at: 2019-11-12T00:50:43-55:00
+---
+
+{% include toc %}
+## Apache ServiceComb Toolkit
+Apache ServiceComb Toolkit is a contract-based microservice development
toolkit. Provides the ability to convert and verify contracts, code, and
documents, helping users quickly build microservice projects based on popular
microservices frameworks and popular programming models, reducing the cost of
microservices entry, enabling users to focus on business development, enhance
refactoring and development efficiency.
+
+
+## Quick Start
+### 1 Build tool and plugins from source
+
+> Build environment requirements
+* [Java 8](http://java.oracle.com)
+* [Apache maven 3.5.0 or greater](http://maven.apache.org/)
+
+```shell
+# Get the latest source code for toolkit from github
+$ git clone https://github.com/apache/servicecomb-toolkit.git
+$ cd toolkit
+
+# Build package
+$ mvn clean install
+```
+
+### 2 Use the toolkit-maven-plugin plugin
+#### 2.1 configuration
+Configured in the pom file of the maven project
+```xml
+<plugin>
+ <groupId>org.apache.servicecomb.toolkit</groupId>
+ <artifactId>toolkit-maven-plugin</artifactId>
+ <version>0.2.0-SNAPSHOT</version>
+ <configuration>
+ <!-- Set to 'code' to resolve the current project. Set to 'contract'
to resolve the contract file for the specified path.If not set, the default is
'code' -->
+ <sourceType>code</sourceType>
+ <!-- The type of the contract file is generated. If it is not set, the
default is 'yaml' -->
+ <contractFileType>yaml</contractFileType>
+ <!-- The type of the generated document. If not set, the default is
'html' -->
+ <documentType>html</documentType>
+ <!-- The root directory to save microservice project,contract file and
document. If it is not set, the default is the 'target' under the directory
where the command is run -->
+ <outputDirectory>./target</outputDirectory>
+ <!-- Input contract file path. Valid when sourceType is set to
'contract', must be set -->
+ <contractLocation>./contract</contractLocation>
+ <!-- Checked contract file path. Valid when sourceType is set to
'contract', must be set -->
+ <sourceContractPath>./target/contract</sourceContractPath>
+ <!-- Sample contract file path, must be set -->
+ <destinationContractPath>./contract</destinationContractPath>
+ <!-- Generated microservice project configuration -->
+ <service>
+ <!-- Microservice type,can generated 'provider/consumer/all',the
default is 'all' -->
+ <serviceType>all</serviceType>
+ <!-- Microservice project 'groupid',optional,the default is
'domain.orgnization.project' -->
+ <groupId>domain.orgnization.project</groupId>
+ <!-- Microservice project 'artifactId',optional,the default is
'sample' -->
+ <artifactId>sample</artifactId>
+ <!-- Microservice project 'artifactVersion',optional,the default
is '0.1.0-SNAPSHOT' -->
+ <artifactVersion>0.1.0-SNAPSHOT</artifactVersion>
+ <!-- Microservice project 'packageName',optional,the default is
'domain.orgnization.project.sample' -->
+ <packageName>domain.orgnization.project.sample</packageName>
+ </service>
+ </configuration>
+</plugin>
+```
+
+#### 2.2 Command
+```shell
+# Generating contract, document and microservice project
+mvn toolkit:generate
+
+# Verify code and contract consistency
+mvn toolkit:verify
+```
+
+#### 2.2.1 Extract the microservice project, OpenAPI contract file and
document from the code
+
+Configuration(use default configuration if not set `<configuration>`)
+
+example
+```xml
+<plugin>
+ <groupId>org.apache.servicecomb.toolkit</groupId>
+ <artifactId>toolkit-maven-plugin</artifactId>
+ <version>0.2.0-SNAPSHOT</version>
+ <configuration>
+ <!-- Set to 'code' to resolve the current project. Set to 'contract'
to resolve the contract file for the specified path.If not set, the default is
'code' -->
+ <sourceType>code</sourceType>
+ <!-- The root directory to save contract file and document. If it is
not set, the default is the 'target' under the directory where the command is
run -->
+ <outputDirectory>./target</outputDirectory>
+ <!-- Generated microservice project configuration -->
+ <service>
+ <!-- Microservice type,can generated 'provider/consumer/all',the
default is 'all' -->
+ <serviceType>all</serviceType>
+ </service>
+ </configuration>
+</plugin>
+```
+
+Run in shell
+```shell
+mvn toolkit:generate
+```
+
+When generating contracts from code,support for identifying restful interfaces
written by the following annotations (class level)
+>RestController, RestSchema, RpcSchema, RequestMapping
+
+When generating contracts from code,the restful interface method access
modifier must be specified as public
+
+
+#### 2.2.2 Generate the microservice project and document from contract
+
+Configuration(use default configuration if not set `<configuration>`)
+
+example
+```xml
+<plugin>
+ <groupId>org.apache.servicecomb.toolkit</groupId>
+ <artifactId>toolkit-maven-plugin</artifactId>
+ <version>0.2.0-SNAPSHOT</version>
+ <configuration>
+ <!-- Set to 'code' to resolve the current project. Set to 'contract'
to resolve the contract file for the specified path.If not set, the default is
'code' -->
+ <sourceType>contract</sourceType>
+ <!-- The root directory to save contract file and document. If it is
not set, the default is the 'target' under the directory where the command is
run -->
+ <outputDirectory>./target</outputDirectory>
+ <!-- Input contract file path. Valid when sourceType is set to
'contract', must be set -->
+ <contractLocation>./contract</contractLocation>
+ <!-- Generated microservice project configuration -->
+ <service>
+ <!-- Microservice type,can generated 'provider/consumer/all',the
default is 'all' -->
+ <serviceType>provider</serviceType>
+ </service>
+ </configuration>
+</plugin>
+```
+
+Run in shell
+```shell
+mvn toolkit:generate
+```
+
+#### 2.2.3 Contract verify
+
+Configuration
+
+example
+```xml
+<plugin>
+ <groupId>org.apache.servicecomb.toolkit</groupId>
+ <artifactId>toolkit-maven-plugin</artifactId>
+ <version>0.2.0-SNAPSHOT</version>
+ <configuration>
+ <!-- Set to 'code' to resolve the current project. Set to 'contract'
to resolve the contract file for the specified path.If not set, the default is
'code' -->
+ <sourceType>code</sourceType>
+ <!-- Sample contract file path, must be set -->
+ <destinationContractPath>./contract</destinationContractPath>
+ </configuration>
+</plugin>
+```
+
+Run in shell
+```shell
+mvn toolkit:verify
+```
+
+
+### 3 Use the toolkit cli
+The executable jar package is located in the toolkit/cli/target/bin directory
+```shell
+$ java -jar toolkit-cli-{version}.jar help
+```
+#### 3.1 Service contract generation microservice project
+```shell
+$ java -jar toolkit-cli-{version}.jar codegenerate -m ServiceComb -i
swagger.yaml -o ./project -p SpringMVC
+```
+> **codegenerate** Command option
+* -m, --microservice-framework. Specify microservices framework, now supports
ServiceComb.
+e.g.：-m ServiceComb
+* -p, --programming-model. Specify programming model, optional JAX-RS, POJO,
SpringMVC, SpringBoot.
+e.g.：-p SpringMvc
+* -i, --input. Specifies contract files that follow the OpenAPI specification,
supports yaml and json formats, and supports specifying local and network
files.
+e.g.：-i http://petstore.swagger.io/v2/swagger.json
+* -o, --output. Generated project code output path.
+e.g.：-o ./project
+* --group-id. Specify the group id of the generated project.
+e.g.：--group-id com.demo
+* --artifact-id. Specify the artifact id of the generated project.
+e.g.：--artifact-id springmvc-example
+* --artifact-version. Specify the artifact version of the generated project.
+e.g.：--artifact-version 1.0.0
+* --api-package : Specify the api package of the generated project.
+e.g.：--api-package com.demo.api
+* --model-package : Specify the model package of the generated project.
+e.g.：--model-package com.demo.model
+* -t, --service-type : Specify microservice type of generated microservice
project. optional value is provider,consumer,all
+e.g.：--service-type provider
+
+#### 3.2 Service contract generation document
+```shell
+$ java -jar toolkit-cli-{version}.jar docgenerate -i swagger.yaml -o ./document
+```
+> **docgenerate** Command option
+* -i, --input. Specifies contract files that follow the OpenAPI specification,
supports yaml and json formats, and supports specifying local and network files.
+e.g：-i http://petstore.swagger.io/v2/swagger.json
+* -o, --output. Document output path.
+e.g：-o ./document
+* -f, --format. Specifies the output document format, now supports swagger-ui
+e.g：-f swagger-ui
+
+#### 3.3 Service contract style checking
+
+```shell
+$ java -jar toolkit-cli-{version}.jar checkstyle oas.yaml
+or
+$ java -jar toolkit-cli-{version}.jar cs oas.yaml
+```
+
+> **checkstyle** Command argument
+* <file> OpenAPI v3 spec yaml file
+
+见[style check rules](/docs/toolkit/oas-validator/#style-check-rules)
+
+#### 3.4 Service contract compatibility checking
+
+```shell
+$ java -jar toolkit-cli-{version}.jar checkcompatibility left-oas.yaml
right-oas.yaml
+or
+$ java -jar toolkit-cli-{version}.jar cc left-oas.yaml right-oas.yaml
+```
+
+> **checkcompatibility** Command argument
+* <files> Two OpenAPI v3 spec yaml file
+
+见[compatibilty check
rules](/docs/toolkit/oas-validator/#compatibility-check-rules)
