Skip to content

Commit d06f15e

Browse files
zxwingzxwing
committed
rest doc samples done
1 parent 9a2374e commit d06f15e

9 files changed

+233
-35
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,4 @@ premium/
2626
.project
2727
.settings
2828
zstack-api.log
29+
.vscode/

‎header/src/main/java/org/zstack/header/vm/APICreateVmInstanceEvent.java

+76
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
11
package org.zstack.header.vm;
22

3+
import org.zstack.header.allocator.HostAllocatorConstant;
34
import org.zstack.header.message.APIEvent;
45
import org.zstack.header.rest.RestResponse;
6+
import org.zstack.header.volume.VolumeInventory;
7+
import org.zstack.header.volume.VolumeState;
8+
import org.zstack.header.volume.VolumeStatus;
9+
import org.zstack.header.volume.VolumeType;
10+
import org.zstack.utils.data.SizeUnit;
11+
12+
import java.sql.Timestamp;
13+
14+
import static org.codehaus.groovy.runtime.InvokerHelper.asList;
515

616
/**
717
* @apiResult api event for message :ref:`APICreateVmInstanceMsg`
@@ -116,4 +126,70 @@ public VmInstanceInventory getInventory() {
116126
public void setInventory(VmInstanceInventory inventory) {
117127
this.inventory = inventory;
118128
}
129+
130+
public static APICreateVmInstanceEvent __example__() {
131+
APICreateVmInstanceEvent evt = new APICreateVmInstanceEvent();
132+
133+
String defaultL3Uuid = uuid();
134+
String rootVolumeUuid = uuid();
135+
136+
VmInstanceInventory vm = new VmInstanceInventory();
137+
vm.setName("Test-VM");
138+
vm.setUuid(uuid());
139+
vm.setAllocatorStrategy(HostAllocatorConstant.LAST_HOST_PREFERRED_ALLOCATOR_STRATEGY_TYPE);
140+
vm.setClusterUuid(uuid());
141+
vm.setCpuNum(1);
142+
vm.setCreateDate(new Timestamp(System.currentTimeMillis()));
143+
vm.setDefaultL3NetworkUuid(defaultL3Uuid);
144+
vm.setDescription("web server VM");
145+
vm.setHostUuid(uuid());
146+
vm.setHypervisorType("KVM");
147+
vm.setImageUuid(uuid());
148+
vm.setInstanceOfferingUuid(uuid());
149+
vm.setLastHostUuid(uuid());
150+
vm.setMemorySize(SizeUnit.GIGABYTE.toByte(8));
151+
vm.setPlatform("Linux");
152+
vm.setRootVolumeUuid(rootVolumeUuid);
153+
vm.setState(VmInstanceState.Running.toString());
154+
vm.setType(VmInstanceConstant.USER_VM_TYPE);
155+
vm.setLastOpDate(new Timestamp(System.currentTimeMillis()));
156+
vm.setZoneUuid(uuid());
157+
158+
VolumeInventory vol = new VolumeInventory();
159+
vol.setName(String.format("Root-Volume-For-VM-%s", vm.getUuid()));
160+
vol.setCreateDate(new Timestamp(System.currentTimeMillis()));
161+
vol.setLastOpDate(new Timestamp(System.currentTimeMillis()));
162+
vol.setType(VolumeType.Root.toString());
163+
vol.setUuid(rootVolumeUuid);
164+
vol.setSize(SizeUnit.GIGABYTE.toByte(100));
165+
vol.setActualSize(SizeUnit.GIGABYTE.toByte(20));
166+
vol.setDeviceId(0);
167+
vol.setState(VolumeState.Enabled.toString());
168+
vol.setFormat("qcow2");
169+
vol.setDiskOfferingUuid(uuid());
170+
vol.setInstallPath(String.format("/zstack_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-%s/%s.qcow2", rootVolumeUuid, rootVolumeUuid));
171+
vol.setStatus(VolumeStatus.Ready.toString());
172+
vol.setPrimaryStorageUuid(uuid());
173+
vol.setVmInstanceUuid(vm.getUuid());
174+
vol.setRootImageUuid(vm.getImageUuid());
175+
vm.setAllVolumes(asList(vol));
176+
177+
VmNicInventory nic = new VmNicInventory();
178+
nic.setVmInstanceUuid(vm.getUuid());
179+
nic.setCreateDate(vm.getCreateDate());
180+
nic.setLastOpDate(vm.getLastOpDate());
181+
nic.setDeviceId(0);
182+
nic.setGateway("192.168.1.1");
183+
nic.setIp("192.168.1.10");
184+
nic.setL3NetworkUuid(defaultL3Uuid);
185+
nic.setNetmask("255.255.255.0");
186+
nic.setMac("00:0c:29:bd:99:fc");
187+
nic.setUsedIpUuid(uuid());
188+
nic.setUuid(uuid());
189+
vm.setVmNics(asList(nic));
190+
191+
evt.setInventory(vm);
192+
193+
return evt;
194+
}
119195
}

‎header/src/main/java/org/zstack/header/vm/APICreateVmInstanceEventDoc_zh_cn.groovy

100644100755
+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import org.zstack.header.vm.VmInstanceInventory
55

66
doc {
77

8-
title "在这里输入结构的名称"
8+
title "云主机清单"
99

1010
ref {
1111
name "error"

‎header/src/main/java/org/zstack/header/vm/APICreateVmInstanceMsg.java

+14
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717

1818
import java.util.List;
1919

20+
import static java.util.Arrays.asList;
21+
2022
/**
2123
* @api create a new vm instance
2224
* @cli
@@ -266,4 +268,16 @@ public String getPrimaryStorageUuidForRootVolume() {
266268
public void setPrimaryStorageUuidForRootVolume(String primaryStorageUuidForRootVolume) {
267269
this.primaryStorageUuidForRootVolume = primaryStorageUuidForRootVolume;
268270
}
271+
272+
public static APICreateVmInstanceMsg __example__() {
273+
APICreateVmInstanceMsg msg = new APICreateVmInstanceMsg();
274+
msg.setName("vm1");
275+
msg.setDescription("this is a vm");
276+
msg.setClusterUuid(uuid());
277+
msg.setDataDiskOfferingUuids(asList(uuid(), uuid()));
278+
msg.setImageUuid(uuid());
279+
msg.setInstanceOfferingUuid(uuid());
280+
msg.setL3NetworkUuids(asList(uuid()));
281+
return msg;
282+
}
269283
}

‎header/src/main/java/org/zstack/header/vm/APICreateVmInstanceMsgDoc_zh_cn.groovy

+20-30
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@ package org.zstack.header.vm
33
import org.zstack.header.vm.APICreateVmInstanceEvent
44

55
doc {
6-
title "CreateVmInstance"
6+
title "创建云主机(CreateVmInstance)"
77

8-
category "vmInstance"
8+
category "云主机"
99

10-
desc "在这里填写API描述"
10+
desc "创建一个新的云主机"
1111

1212
rest {
1313
request {
@@ -25,7 +25,7 @@ doc {
2525
column {
2626
name "name"
2727
enclosedIn "params"
28-
desc "资源名称"
28+
desc "云主机名称"
2929
location "body"
3030
type "String"
3131
optional false
@@ -35,7 +35,7 @@ doc {
3535
column {
3636
name "instanceOfferingUuid"
3737
enclosedIn "params"
38-
desc "计算规格UUID"
38+
desc "计算规格UUID。指定云主机的CPU、内存等参数。"
3939
location "body"
4040
type "String"
4141
optional false
@@ -45,7 +45,7 @@ doc {
4545
column {
4646
name "imageUuid"
4747
enclosedIn "params"
48-
desc "镜像UUID"
48+
desc "镜像UUID。云主机的根云盘会从该字段指定的镜像创建。"
4949
location "body"
5050
type "String"
5151
optional false
@@ -55,7 +55,7 @@ doc {
5555
column {
5656
name "l3NetworkUuids"
5757
enclosedIn "params"
58-
desc ""
58+
desc "三层网络UUID列表。可以指定一个或多个三层网络，云主机会在每个网络上创建一个网卡。"
5959
location "body"
6060
type "List"
6161
optional false
@@ -65,7 +65,7 @@ doc {
6565
column {
6666
name "type"
6767
enclosedIn "params"
68-
desc ""
68+
desc "云主机类型。保留字段，无需指定。"
6969
location "body"
7070
type "String"
7171
optional true
@@ -75,7 +75,7 @@ doc {
7575
column {
7676
name "rootDiskOfferingUuid"
7777
enclosedIn "params"
78-
desc ""
78+
desc "根云盘规格UUID。如果`imageUuid`字段指定的镜像类型是ISO，该字段必须指定以确定需要创建的根云盘大小。如果镜像类型是非ISO，该字段无需指定。"
7979
location "body"
8080
type "String"
8181
optional true
@@ -85,7 +85,7 @@ doc {
8585
column {
8686
name "dataDiskOfferingUuids"
8787
enclosedIn "params"
88-
desc ""
88+
desc "云盘规格UUID列表。可以指定一个或多个云盘规格UUID（UUID可以重复）为云主机创建一个或多个数据云盘。"
8989
location "body"
9090
type "List"
9191
optional true
@@ -95,7 +95,7 @@ doc {
9595
column {
9696
name "zoneUuid"
9797
enclosedIn "params"
98-
desc "区域UUID"
98+
desc "区域UUID。若指定，云主机会在指定区域创建。"
9999
location "body"
100100
type "String"
101101
optional true
@@ -105,7 +105,7 @@ doc {
105105
column {
106106
name "clusterUuid"
107107
enclosedIn "params"
108-
desc "集群UUID"
108+
desc "集群UUID。若指定，云主机会在指定集群创建，该字段优先级高于`zoneUuid`。"
109109
location "body"
110110
type "String"
111111
optional true
@@ -115,7 +115,7 @@ doc {
115115
column {
116116
name "hostUuid"
117117
enclosedIn "params"
118-
desc "物理机UUID"
118+
desc "物理机UUID。若指定，云主机会在指定物理机创建，该字段优先级高于`zoneUuid`和`clusterUuid`。"
119119
location "body"
120120
type "String"
121121
optional true
@@ -125,17 +125,17 @@ doc {
125125
column {
126126
name "primaryStorageUuidForRootVolume"
127127
enclosedIn "params"
128-
desc ""
128+
desc "主存储UUID。若指定，云主机的根云盘会在指定主存储创建。"
129129
location "body"
130130
type "String"
131131
optional true
132-
since "0.6"
132+
since "1.8"
133133

134134
}
135135
column {
136136
name "description"
137137
enclosedIn "params"
138-
desc "资源的详细描述"
138+
desc "云主机的详细描述"
139139
location "body"
140140
type "String"
141141
optional true
@@ -145,27 +145,17 @@ doc {
145145
column {
146146
name "defaultL3NetworkUuid"
147147
enclosedIn "params"
148-
desc ""
148+
desc "默认三层网络UUID。当在`l3NetworkUuids`指定了多个三层网络时，该字段指定提供默认路由的三层网络。若不指定，`l3NetworkUuids`的第一个网络被选为默认网络。"
149149
location "body"
150150
type "String"
151151
optional true
152152
since "0.6"
153153

154154
}
155-
column {
156-
name "strategy"
157-
enclosedIn "params"
158-
desc ""
159-
location "body"
160-
type "String"
161-
optional true
162-
since "0.6"
163-
values ("InstantStart","JustCreate")
164-
}
165155
column {
166156
name "resourceUuid"
167157
enclosedIn "params"
168-
desc ""
158+
desc "资源UUID。若指定，云主机会使用该字段值作为UUID。"
169159
location "body"
170160
type "String"
171161
optional true
@@ -175,7 +165,7 @@ doc {
175165
column {
176166
name "systemTags"
177167
enclosedIn ""
178-
desc ""
168+
desc "云主机系统标签"
179169
location "body"
180170
type "List"
181171
optional true
@@ -185,7 +175,7 @@ doc {
185175
column {
186176
name "userTags"
187177
enclosedIn ""
188-
desc ""
178+
desc "云主机用户标签"
189179
location "body"
190180
type "List"
191181
optional true

‎header/src/main/java/org/zstack/header/vm/APIQueryVmInstanceMsg.java

+7-1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66
import org.zstack.header.query.AutoQuery;
77
import org.zstack.header.rest.RestRequest;
88

9+
import java.util.List;
10+
11+
import static java.util.Arrays.asList;
12+
913
@AutoQuery(replyClass = APIQueryVmInstanceReply.class, inventoryClass = VmInstanceInventory.class)
1014
@Action(category = VmInstanceConstant.ACTION_CATEGORY, names = {"read"})
1115
@RestRequest(
@@ -15,5 +19,7 @@
1519
method = HttpMethod.GET
1620
)
1721
public class APIQueryVmInstanceMsg extends APIQueryMessage {
18-
22+
public static List<String> __example__() {
23+
return asList("name=vm1", "vmNics.ip=192.168.20.100");
24+
}
1925
}

‎header/src/main/java/org/zstack/header/vm/APIQueryVmInstanceMsgDoc_zh_cn.groovy

100644100755
+3-3
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ import org.zstack.header.vm.APIQueryVmInstanceReply
44
import org.zstack.header.query.APIQueryMessage
55

66
doc {
7-
title "QueryVmInstance"
7+
title "查询云主机(QueryVmInstance)"
88

9-
category "vmInstance"
9+
category "云主机"
1010

11-
desc "在这里填写API描述"
11+
desc "查询云主机"
1212

1313
rest {
1414
request {

0 commit comments

Comments
 (0)