diff --git a/docs/api/examples/post_project.txt b/docs/api/examples/post_project.txt index bc57a383..8054c97f 100644 --- a/docs/api/examples/post_project.txt +++ b/docs/api/examples/post_project.txt @@ -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" } diff --git a/docs/api/project.rst b/docs/api/project.rst new file mode 100644 index 00000000..00e354f2 --- /dev/null +++ b/docs/api/project.rst @@ -0,0 +1,39 @@ +/project +--------------------------------------------- + +.. contents:: + +POST /project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create a project on the server + +Response status codes +********************** +- **200**: OK + +Input +******* +.. raw:: html + + + + + +
Name Mandatory Type Description
location string Base directory where the project should be created on remote server
uuid string Project UUID
+ +Output +******* +.. raw:: html + + + + + +
Name Mandatory Type Description
location string Base directory where the project should be created on remote server
uuid string Project UUID
+ +Sample session +*************** + + +.. literalinclude:: examples/post_project.txt + diff --git a/docs/api/version.rst b/docs/api/version.rst index a5c86f19..66da7325 100644 --- a/docs/api/version.rst +++ b/docs/api/version.rst @@ -1,14 +1,14 @@ /version ------------------------------- +--------------------------------------------- .. contents:: GET /version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Retrieve server version number +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Retrieve the server version number Response status codes -************************** +********************** - **200**: OK Output @@ -16,8 +16,8 @@ Output .. raw:: html - - + +
NameMandatoryTypeDescription
version✔stringVersion number human readable
Name Mandatory Type Description
version ✔ string Version number human readable
Sample session @@ -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 + + + + +
Name Mandatory Type Description
version ✔ string Version number human readable
+ +Output +******* +.. raw:: html + + + + +
Name Mandatory Type Description
version ✔ string Version number human readable
+ +Sample session +*************** + + +.. literalinclude:: examples/post_version.txt + diff --git a/docs/api/vpcs.rst b/docs/api/vpcs.rst index b800f755..225990bb 100644 --- a/docs/api/vpcs.rst +++ b/docs/api/vpcs.rst @@ -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 @@ -21,10 +17,12 @@ Input .. raw:: html - - - - + + + + + +
NameMandatoryTypeDescription
console integerconsole TCP port
name✔stringVPCS device name
vpcs_id integerVPCS device instance ID
Name Mandatory Type Description
console integer console TCP port
name ✔ string VPCS device name
project_uuid ✔ string Project UUID
uuid string VPCS device UUID
vpcs_id integer VPCS device instance ID (for project created before GNS3 1.3)
Output @@ -32,10 +30,11 @@ Output .. raw:: html - - - - + + + + +
NameMandatoryTypeDescription
console✔integerconsole TCP port
name✔stringVPCS device name
vpcs_id✔integerVPCS device instance ID
Name Mandatory Type Description
console ✔ integer console TCP port
name ✔ string VPCS device name
project_uuid ✔ string Project UUID
uuid ✔ string VPCS device UUID
Sample session diff --git a/docs/api/vpcsuuidportsportidnio.rst b/docs/api/vpcsuuidportsportidnio.rst new file mode 100644 index 00000000..03f2deaf --- /dev/null +++ b/docs/api/vpcsuuidportsportidnio.rst @@ -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 + diff --git a/docs/api/vpcsuuidstart.rst b/docs/api/vpcsuuidstart.rst new file mode 100644 index 00000000..a55d296b --- /dev/null +++ b/docs/api/vpcsuuidstart.rst @@ -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 + diff --git a/docs/api/vpcsuuidstop.rst b/docs/api/vpcsuuidstop.rst new file mode 100644 index 00000000..ceff8f62 --- /dev/null +++ b/docs/api/vpcsuuidstop.rst @@ -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 + diff --git a/docs/api/vpcsvpcsid.rst b/docs/api/vpcsvpcsid.rst deleted file mode 100644 index 20db8f9f..00000000 --- a/docs/api/vpcsvpcsid.rst +++ /dev/null @@ -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 - - - - - - -
NameMandatoryTypeDescription
console✔integerconsole TCP port
name✔stringVPCS device name
vpcs_id✔integerVPCS device instance ID
- - -PUT /vpcs/{vpcs_id} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Update VPCS informations - -Parameters -********** -- **vpcs_id**: Id of VPCS instance - -Response status codes -************************** -- **200**: OK - -Input -******* -.. raw:: html - - - - - - -
NameMandatoryTypeDescription
console✔integerconsole TCP port
name✔stringVPCS device name
vpcs_id✔integerVPCS device instance ID
- -Output -******* -.. raw:: html - - - - - - -
NameMandatoryTypeDescription
console✔integerconsole TCP port
name✔stringVPCS device name
vpcs_id✔integerVPCS device instance ID
- diff --git a/docs/api/vpcsvpcsidnio.rst b/docs/api/vpcsvpcsidnio.rst deleted file mode 100644 index 14a9a6db..00000000 --- a/docs/api/vpcsvpcsidnio.rst +++ /dev/null @@ -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 - - - - - -
NameMandatoryTypeDescription
ethernet_device✔stringEthernet device name e.g. eth0
type✔enumPossible values: nio_generic_ethernet
- -LinuxEthernet -^^^^^^^^^^^^^^^^ -Linux Ethernet Network Input/Output - -.. raw:: html - - - - - -
NameMandatoryTypeDescription
ethernet_device✔stringEthernet device name e.g. eth0
type✔enumPossible values: nio_linux_ethernet
- -NULL -^^^^^^^^^^^^^^^^ -NULL Network Input/Output - -.. raw:: html - - - - -
NameMandatoryTypeDescription
type✔enumPossible values: nio_null
- -TAP -^^^^^^^^^^^^^^^^ -TAP Network Input/Output - -.. raw:: html - - - - - -
NameMandatoryTypeDescription
tap_device✔stringTAP device name e.g. tap0
type✔enumPossible values: nio_tap
- -UDP -^^^^^^^^^^^^^^^^ -UDP Network Input/Output - -.. raw:: html - - - - - - - -
NameMandatoryTypeDescription
lport✔integerLocal port
rhost✔stringRemote host
rport✔integerRemote port
type✔enumPossible values: nio_udp
- -UNIX -^^^^^^^^^^^^^^^^ -UNIX Network Input/Output - -.. raw:: html - - - - - - -
NameMandatoryTypeDescription
local_file✔stringpath to the UNIX socket file (local)
remote_file✔stringpath to the UNIX socket file (remote)
type✔enumPossible values: nio_unix
- -VDE -^^^^^^^^^^^^^^^^ -VDE Network Input/Output - -.. raw:: html - - - - - - -
NameMandatoryTypeDescription
control_file✔stringpath to the VDE control file
local_file✔stringpath to the VDE control file
type✔enumPossible values: nio_vde
- -Body -+++++++++ -.. raw:: html - - - - - - - -
NameMandatoryTypeDescription
id✔integerVPCS device instance ID
nio✔UDP, Ethernet, LinuxEthernet, TAP, UNIX, VDE, NULLNetwork Input/Output
port✔integerPort number
port_id✔integerUnique port identifier for the VPCS instance
- -Sample session -*************** - - -.. literalinclude:: examples/post_vpcsvpcsidnio.txt - diff --git a/gns3server/web/documentation.py b/gns3server/web/documentation.py index b699f9dd..2c165f8b 100644 --- a/gns3server/web/documentation.py +++ b/gns3server/web/documentation.py @@ -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() diff --git a/scripts/documentation.sh b/scripts/documentation.sh index 92d458f7..0ee22a9a 100755 --- a/scripts/documentation.sh +++ b/scripts/documentation.sh @@ -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