Update examples only when launching test with documentation.sh

docs/api/examples/get_vpcsuuid.txt

@@ -18,5 +18,5 @@ X-ROUTE: /vpcs/{uuid}
     "project_uuid": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
     "script_file": null,
     "startup_script": null,
-    "uuid": "f8155d67-c0bf-4229-be4c-97edaaae7b0b"
+    "uuid": "c9e15d9f-cff3-402a-b9c9-57f4d008832f"
 }

docs/api/examples/post_vpcs.txt

@@ -21,5 +21,5 @@ X-ROUTE: /vpcs
     "project_uuid": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
     "script_file": null,
     "startup_script": null,
-    "uuid": "5a9aac64-5b62-41bd-955a-fcef90a2fac5"
+    "uuid": "f5016337-fa62-4e82-95da-9f66f68e6e8f"
 }

docs/api/virtualbox.rst

@@ -0,0 +1,47 @@
+/virtualbox
+---------------------------------------------
+
+.. contents::
+
+POST /virtualbox
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Create a new VirtualBox VM instance
+
+Response status codes
+**********************
+- **400**: Invalid project UUID
+- **201**: VirtualBox VM instance created
+- **409**: Conflict
+
+Input
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>linked_clone</td>                    <td> </td>                     <td>boolean</td>                     <td>either the VM is a linked clone or not</td>                     </tr>
+    <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VirtualBox VM instance name</td>                     </tr>
+    <tr><td>project_uuid</td>                    <td> </td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>uuid</td>                    <td> </td>                     <td>string</td>                     <td>VirtualBox VM instance UUID</td>                     </tr>
+    <tr><td>vbox_id</td>                    <td> </td>                     <td>integer</td>                     <td>VirtualBox VM instance ID (for project created before GNS3 1.3)</td>                     </tr>
+    <tr><td>vmname</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VirtualBox VM name (in VirtualBox itself)</td>                     </tr>
+    </table>
+
+Output
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>console</td>                    <td> </td>                     <td>integer</td>                     <td>console TCP port</td>                     </tr>
+    <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VirtualBox VM instance name</td>                     </tr>
+    <tr><td>project_uuid</td>                    <td> </td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VirtualBox VM instance UUID</td>                     </tr>
+    </table>
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/post_virtualbox.txt
+

docs/api/virtualboxuuidstart.rst

@@ -0,0 +1,25 @@
+/virtualbox/{uuid}/start
+---------------------------------------------
+
+.. contents::
+
+POST /virtualbox/**{uuid}**/start
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Start a VirtualBox VM instance
+
+Parameters
+**********
+- **uuid**: VirtualBox VM instance UUID
+
+Response status codes
+**********************
+- **400**: Invalid VirtualBox VM instance UUID
+- **404**: VirtualBox VM instance doesn't exist
+- **204**: VirtualBox VM instance started
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/post_virtualboxuuidstart.txt
+

docs/api/virtualboxuuidstop.rst

@@ -0,0 +1,25 @@
+/virtualbox/{uuid}/stop
+---------------------------------------------
+
+.. contents::
+
+POST /virtualbox/**{uuid}**/stop
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Stop a VirtualBox VM instance
+
+Parameters
+**********
+- **uuid**: VirtualBox VM instance UUID
+
+Response status codes
+**********************
+- **400**: Invalid VirtualBox VM instance UUID
+- **404**: VirtualBox VM instance doesn't exist
+- **204**: VirtualBox VM instance stopped
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/post_virtualboxuuidstop.txt
+

docs/api/vpcs.rst

@@ -9,6 +9,7 @@ Create a new VPCS instance
 
 Response status codes
 **********************
+- **400**: Invalid project UUID
 - **201**: VPCS instance created
 - **409**: Conflict
 
@@ -18,9 +19,11 @@ Input
 
     <table>
     <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
-    <tr><td>console</td>                    <td> </td>                     <td>integer</td>                     <td>console TCP port</td>                     </tr>
+    <tr><td>console</td>                    <td> </td>                     <td>['integer', 'null']</td>                     <td>console TCP port</td>                     </tr>
     <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device name</td>                     </tr>
     <tr><td>project_uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>script_file</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>VPCS startup script</td>                     </tr>
+    <tr><td>startup_script</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>Content of the VPCS startup script</td>                     </tr>
     <tr><td>uuid</td>                    <td> </td>                     <td>string</td>                     <td>VPCS device UUID</td>                     </tr>
     <tr><td>vpcs_id</td>                    <td> </td>                     <td>integer</td>                     <td>VPCS device instance ID (for project created before GNS3 1.3)</td>                     </tr>
     </table>
@@ -34,6 +37,8 @@ Output
     <tr><td>console</td>                    <td>&#10004;</td>                     <td>integer</td>                     <td>console TCP port</td>                     </tr>
     <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device name</td>                     </tr>
     <tr><td>project_uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>script_file</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>VPCS startup script</td>                     </tr>
+    <tr><td>startup_script</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>Content of the VPCS startup script</td>                     </tr>
     <tr><td>uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device UUID</td>                     </tr>
     </table>
 

docs/api/vpcsuuid.rst

@@ -0,0 +1,60 @@
+/vpcs/{uuid}
+---------------------------------------------
+
+.. contents::
+
+GET /vpcs/**{uuid}**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Get a VPCS instance
+
+Parameters
+**********
+- **uuid**: VPCS instance UUID
+
+Response status codes
+**********************
+- **200**: VPCS instance started
+- **404**: VPCS instance doesn't exist
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/get_vpcsuuid.txt
+
+
+PUT /vpcs/**{uuid}**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Update a VPCS instance
+
+Response status codes
+**********************
+- **200**: VPCS instance updated
+- **409**: Conflict
+
+Input
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>console</td>                    <td> </td>                     <td>['integer', 'null']</td>                     <td>console TCP port</td>                     </tr>
+    <tr><td>name</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>VPCS device name</td>                     </tr>
+    <tr><td>script_file</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>VPCS startup script</td>                     </tr>
+    <tr><td>startup_script</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>Content of the VPCS startup script</td>                     </tr>
+    </table>
+
+Output
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>console</td>                    <td>&#10004;</td>                     <td>integer</td>                     <td>console TCP port</td>                     </tr>
+    <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device name</td>                     </tr>
+    <tr><td>project_uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>script_file</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>VPCS startup script</td>                     </tr>
+    <tr><td>startup_script</td>                    <td> </td>                     <td>['string', 'null']</td>                     <td>Content of the VPCS startup script</td>                     </tr>
+    <tr><td>uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device UUID</td>                     </tr>
+    </table>
+

scripts/documentation.sh

@@ -23,6 +23,8 @@ set -e
 
 echo "WARNING: This script should be run at the root directory of the project"
 
+export PYTEST_BUILD_DOCUMENTATION=1
+
 py.test -v
 python3 gns3server/web/documentation.py
 cd docs

tests/api/base.py

@@ -25,7 +25,7 @@ import socket
 import pytest
 from aiohttp import web
 import aiohttp
-
+import os
 
 from gns3server.web.route import Route
 # TODO: get rid of *
@@ -93,7 +93,7 @@ class Query:
                 response.json = None
         else:
             response.json = {}
-        if kwargs.get('example'):
+        if kwargs.get('example') and os.environ.get("PYTEST_BUILD_DOCUMENTATION") == "1":
             self._dump_example(method, response.route, body, response)
         return response