mirror of
https://github.com/GNS3/gns3-server
synced 2024-11-30 20:28:08 +00:00
Fix documentation generation
This commit is contained in:
Julien Duponchelle
parent
0b97509a74
commit
f5ac73d1ca
@ -1,8 +1,8 @@
|
||||
curl -i -X POST 'http://localhost:8000/project' -d '{"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-321/test_create_project_with_dir0"}'
|
||||
curl -i -X POST 'http://localhost:8000/project' -d '{"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-328/test_create_project_with_dir0"}'
|
||||
|
||||
POST /project HTTP/1.1
|
||||
{
|
||||
"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-321/test_create_project_with_dir0"
|
||||
"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-328/test_create_project_with_dir0"
|
||||
}
|
||||
|
||||
|
||||
@ -15,6 +15,6 @@ SERVER: Python/3.4 aiohttp/0.13.1
|
||||
X-ROUTE: /project
|
||||
|
||||
{
|
||||
"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-321/test_create_project_with_dir0",
|
||||
"uuid": "a00bbbdf-4088-4634-816d-513e0428275f"
|
||||
"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-328/test_create_project_with_dir0",
|
||||
"uuid": "b4432fe3-6743-4ce7-ab05-1f5637d04cd6"
|
||||
}
|
||||
|
||||
39
docs/api/project.rst
Normal file
39
docs/api/project.rst
Normal file
@ -0,0 +1,39 @@
|
||||
/project
|
||||
---------------------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
POST /project
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Create a project on the server
|
||||
|
||||
Response status codes
|
||||
**********************
|
||||
- **200**: OK
|
||||
|
||||
Input
|
||||
*******
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr> <th>Name</th> <th>Mandatory</th> <th>Type</th> <th>Description</th> </tr>
|
||||
<tr><td>location</td> <td> </td> <td>string</td> <td>Base directory where the project should be created on remote server</td> </tr>
|
||||
<tr><td>uuid</td> <td> </td> <td>string</td> <td>Project UUID</td> </tr>
|
||||
</table>
|
||||
|
||||
Output
|
||||
*******
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr> <th>Name</th> <th>Mandatory</th> <th>Type</th> <th>Description</th> </tr>
|
||||
<tr><td>location</td> <td> </td> <td>string</td> <td>Base directory where the project should be created on remote server</td> </tr>
|
||||
<tr><td>uuid</td> <td> </td> <td>string</td> <td>Project UUID</td> </tr>
|
||||
</table>
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/post_project.txt
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
/version
|
||||
------------------------------
|
||||
---------------------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
GET /version
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Retrieve server version number
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Retrieve the server version number
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
**********************
|
||||
- **200**: OK
|
||||
|
||||
Output
|
||||
@ -26,3 +26,37 @@ Sample session
|
||||
|
||||
.. literalinclude:: examples/get_version.txt
|
||||
|
||||
|
||||
POST /version
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Check if version is the same as the server
|
||||
|
||||
Response status codes
|
||||
**********************
|
||||
- **200**: Same version
|
||||
- **409**: Invalid version
|
||||
|
||||
Input
|
||||
*******
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr> <th>Name</th> <th>Mandatory</th> <th>Type</th> <th>Description</th> </tr>
|
||||
<tr><td>version</td> <td>✔</td> <td>string</td> <td>Version number human readable</td> </tr>
|
||||
</table>
|
||||
|
||||
Output
|
||||
*******
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr> <th>Name</th> <th>Mandatory</th> <th>Type</th> <th>Description</th> </tr>
|
||||
<tr><td>version</td> <td>✔</td> <td>string</td> <td>Version number human readable</td> </tr>
|
||||
</table>
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/post_version.txt
|
||||
|
||||
|
||||
@ -1,19 +1,15 @@
|
||||
/vpcs
|
||||
------------------------------
|
||||
---------------------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
POST /vpcs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Create a new VPCS and return it
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **vpcs_id**: Id of VPCS instance
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Create a new VPCS instance
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
- **201**: Success of creation of VPCS
|
||||
**********************
|
||||
- **201**: VPCS instance created
|
||||
- **409**: Conflict
|
||||
|
||||
Input
|
||||
@ -24,7 +20,9 @@ Input
|
||||
<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>✔</td> <td>string</td> <td>VPCS device name</td> </tr>
|
||||
<tr><td>vpcs_id</td><td> </td><td>integer</td><td>VPCS device instance ID</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>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>
|
||||
|
||||
Output
|
||||
@ -35,7 +33,8 @@ Output
|
||||
<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>✔</td> <td>string</td> <td>VPCS device name</td> </tr>
|
||||
<tr><td>vpcs_id</td><td>✔</td><td>integer</td><td>VPCS device instance ID</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>VPCS device UUID</td> </tr>
|
||||
</table>
|
||||
|
||||
Sample session
|
||||
|
||||
48
docs/api/vpcsuuidportsportidnio.rst
Normal file
48
docs/api/vpcsuuidportsportidnio.rst
Normal file
@ -0,0 +1,48 @@
|
||||
/vpcs/{uuid}/ports/{port_id}/nio
|
||||
---------------------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
POST /vpcs/{uuid}/ports/{port_id}/nio
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Add a NIO to a VPCS
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **port_id**: Id of the port where the nio should be add
|
||||
- **uuid**: VPCS instance UUID
|
||||
|
||||
Response status codes
|
||||
**********************
|
||||
- **400**: Invalid VPCS instance UUID
|
||||
- **201**: NIO created
|
||||
- **404**: VPCS instance doesn't exist
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/post_vpcsuuidportsportidnio.txt
|
||||
|
||||
|
||||
DELETE /vpcs/{uuid}/ports/{port_id}/nio
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Remove a NIO from a VPCS
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **port_id**: ID of the port where the nio should be removed
|
||||
- **uuid**: VPCS instance UUID
|
||||
|
||||
Response status codes
|
||||
**********************
|
||||
- **200**: NIO deleted
|
||||
- **400**: Invalid VPCS instance UUID
|
||||
- **404**: VPCS instance doesn't exist
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/delete_vpcsuuidportsportidnio.txt
|
||||
|
||||
19
docs/api/vpcsuuidstart.rst
Normal file
19
docs/api/vpcsuuidstart.rst
Normal file
@ -0,0 +1,19 @@
|
||||
/vpcs/{uuid}/start
|
||||
---------------------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
POST /vpcs/{uuid}/start
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Start a VPCS instance
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **uuid**: VPCS instance UUID
|
||||
|
||||
Response status codes
|
||||
**********************
|
||||
- **400**: Invalid VPCS instance UUID
|
||||
- **404**: VPCS instance doesn't exist
|
||||
- **204**: VPCS instance started
|
||||
|
||||
19
docs/api/vpcsuuidstop.rst
Normal file
19
docs/api/vpcsuuidstop.rst
Normal file
@ -0,0 +1,19 @@
|
||||
/vpcs/{uuid}/stop
|
||||
---------------------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
POST /vpcs/{uuid}/stop
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Stop a VPCS instance
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **uuid**: VPCS instance UUID
|
||||
|
||||
Response status codes
|
||||
**********************
|
||||
- **400**: Invalid VPCS instance UUID
|
||||
- **404**: VPCS instance doesn't exist
|
||||
- **204**: VPCS instance stopped
|
||||
|
||||
@ -1,63 +0,0 @@
|
||||
/vpcs/{vpcs_id}
|
||||
------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
GET /vpcs/{vpcs_id}
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Get informations about a VPCS
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **vpcs_id**: Id of VPCS instance
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
- **200**: OK
|
||||
|
||||
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>✔</td><td>string</td><td>VPCS device name</td></tr>
|
||||
<tr><td>vpcs_id</td><td>✔</td><td>integer</td><td>VPCS device instance ID</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
PUT /vpcs/{vpcs_id}
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Update VPCS informations
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **vpcs_id**: Id of VPCS instance
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
- **200**: OK
|
||||
|
||||
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</td><td>console TCP port</td></tr>
|
||||
<tr><td>name</td><td>✔</td><td>string</td><td>VPCS device name</td></tr>
|
||||
<tr><td>vpcs_id</td><td>✔</td><td>integer</td><td>VPCS device instance ID</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>✔</td><td>string</td><td>VPCS device name</td></tr>
|
||||
<tr><td>vpcs_id</td><td>✔</td><td>integer</td><td>VPCS device instance ID</td></tr>
|
||||
</table>
|
||||
|
||||
@ -1,127 +0,0 @@
|
||||
/vpcs/{vpcs_id}/nio
|
||||
------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
POST /vpcs/{vpcs_id}/nio
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
ADD NIO to a VPCS
|
||||
|
||||
Parameters
|
||||
**********
|
||||
- **vpcs_id**: Id of VPCS instance
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
- **201**: Success of creation of NIO
|
||||
- **409**: Conflict
|
||||
|
||||
Input
|
||||
*******
|
||||
Types
|
||||
+++++++++
|
||||
Ethernet
|
||||
^^^^^^^^^^^^^^^^
|
||||
Generic Ethernet Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>ethernet_device</td><td>✔</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_generic_ethernet</td></tr>
|
||||
</table>
|
||||
|
||||
LinuxEthernet
|
||||
^^^^^^^^^^^^^^^^
|
||||
Linux Ethernet Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>ethernet_device</td><td>✔</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_linux_ethernet</td></tr>
|
||||
</table>
|
||||
|
||||
NULL
|
||||
^^^^^^^^^^^^^^^^
|
||||
NULL Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_null</td></tr>
|
||||
</table>
|
||||
|
||||
TAP
|
||||
^^^^^^^^^^^^^^^^
|
||||
TAP Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>tap_device</td><td>✔</td><td>string</td><td>TAP device name e.g. tap0</td></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_tap</td></tr>
|
||||
</table>
|
||||
|
||||
UDP
|
||||
^^^^^^^^^^^^^^^^
|
||||
UDP Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>lport</td><td>✔</td><td>integer</td><td>Local port</td></tr>
|
||||
<tr><td>rhost</td><td>✔</td><td>string</td><td>Remote host</td></tr>
|
||||
<tr><td>rport</td><td>✔</td><td>integer</td><td>Remote port</td></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_udp</td></tr>
|
||||
</table>
|
||||
|
||||
UNIX
|
||||
^^^^^^^^^^^^^^^^
|
||||
UNIX Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>local_file</td><td>✔</td><td>string</td><td>path to the UNIX socket file (local)</td></tr>
|
||||
<tr><td>remote_file</td><td>✔</td><td>string</td><td>path to the UNIX socket file (remote)</td></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_unix</td></tr>
|
||||
</table>
|
||||
|
||||
VDE
|
||||
^^^^^^^^^^^^^^^^
|
||||
VDE Network Input/Output
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>control_file</td><td>✔</td><td>string</td><td>path to the VDE control file</td></tr>
|
||||
<tr><td>local_file</td><td>✔</td><td>string</td><td>path to the VDE control file</td></tr>
|
||||
<tr><td>type</td><td>✔</td><td>enum</td><td>Possible values: nio_vde</td></tr>
|
||||
</table>
|
||||
|
||||
Body
|
||||
+++++++++
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
|
||||
<tr><td>id</td><td>✔</td><td>integer</td><td>VPCS device instance ID</td></tr>
|
||||
<tr><td>nio</td><td>✔</td><td>UDP, Ethernet, LinuxEthernet, TAP, UNIX, VDE, NULL</td><td>Network Input/Output</td></tr>
|
||||
<tr><td>port</td><td>✔</td><td>integer</td><td>Port number</td></tr>
|
||||
<tr><td>port_id</td><td>✔</td><td>integer</td><td>Unique port identifier for the VPCS instance</td></tr>
|
||||
</table>
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/post_vpcsvpcsidnio.txt
|
||||
|
||||
@ -18,6 +18,7 @@
|
||||
import re
|
||||
import os.path
|
||||
|
||||
from gns3server.handlers import *
|
||||
from gns3server.web.route import Route
|
||||
|
||||
|
||||
@ -33,11 +34,11 @@ class Documentation(object):
|
||||
filename = self._file_path(path)
|
||||
handler_doc = self._documentation[path]
|
||||
with open("docs/api/{}.rst".format(filename), 'w+') as f:
|
||||
f.write('{}\n------------------------------\n\n'.format(path))
|
||||
f.write('{}\n---------------------------------------------\n\n'.format(path))
|
||||
f.write('.. contents::\n')
|
||||
for method in handler_doc["methods"]:
|
||||
f.write('\n{} {}\n'.format(method["method"], path))
|
||||
f.write('~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n')
|
||||
f.write('~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n')
|
||||
f.write('{}\n\n'.format(method["description"]))
|
||||
|
||||
if len(method["parameters"]) > 0:
|
||||
@ -47,7 +48,7 @@ class Documentation(object):
|
||||
f.write("- **{}**: {}\n".format(parameter, desc))
|
||||
f.write("\n")
|
||||
|
||||
f.write("Response status codes\n*******************\n")
|
||||
f.write("Response status codes\n**********************\n")
|
||||
for code in method["status_codes"]:
|
||||
desc = method["status_codes"][code]
|
||||
f.write("- **{}**: {}\n".format(code, desc))
|
||||
@ -56,11 +57,11 @@ class Documentation(object):
|
||||
if "properties" in method["input_schema"]:
|
||||
f.write("Input\n*******\n")
|
||||
self._write_definitions(f, method["input_schema"])
|
||||
self.__write_json_schema(f, method["input_schema"])
|
||||
self._write_json_schema(f, method["input_schema"])
|
||||
|
||||
if "properties" in method["output_schema"]:
|
||||
f.write("Output\n*******\n")
|
||||
self.__write_json_schema(f, method["output_schema"])
|
||||
self._write_json_schema(f, method["output_schema"])
|
||||
|
||||
self._include_query_example(f, method, path)
|
||||
|
||||
@ -130,4 +131,5 @@ class Documentation(object):
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
print("Generate API documentation")
|
||||
Documentation(Route).write()
|
||||
|
||||
@ -21,7 +21,9 @@
|
||||
|
||||
set -e
|
||||
|
||||
py.test
|
||||
python3 ../gns3server/web/documentation.py
|
||||
cd ../docs
|
||||
echo "WARNING: This script should be run at the root directory of the project"
|
||||
|
||||
py.test -v
|
||||
python3 gns3server/web/documentation.py
|
||||
cd docs
|
||||
make html
|
||||
|
||||
Loading…
Reference in New Issue
Block a user