From e2086c72b8d42984e64b27ec7b52057f6c741097 Mon Sep 17 00:00:00 2001 From: Vasilis Tsiligiannis Date: Mon, 21 Sep 2020 13:13:06 +0300 Subject: [PATCH] satnogs-db-api-client: Generate API documentation Generate API documentation from OpenAPI specification. Also, update outdated Sphinx documentation and include the generated docs. Signed-off-by: Vasilis Tsiligiannis --- .gitlab-ci.yml | 8 +++ docs/api-satellites.rst | 25 ------- docs/api-transmitters.rst | 65 ------------------- docs/api.rst | 24 ++++--- .../openapi-generator-config.json | 12 +++- 5 files changed, 35 insertions(+), 99 deletions(-) delete mode 100644 docs/api-satellites.rst delete mode 100644 docs/api-transmitters.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 23f1561..57ccb06 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -76,6 +76,13 @@ api: -g python -o satnogs-db-api-client -c satnogs-db-api-client/openapi-generator-config.json + - >- + docker-entrypoint.sh + generate + -i satnogs-db-api-client/api-schema.yml + -g html2 + -o satnogs-db-api-client/html2 + -c satnogs-db-api-client/openapi-generator-config.json artifacts: expire_in: 1 week when: always @@ -105,6 +112,7 @@ docs: before_script: - pip install "$GITLAB_CI_PYPI_TOX" script: + - cp -a satnogs-db-api-client/html2 docs/_static/api - rm -rf docs/_build - tox -e "docs" artifacts: diff --git a/docs/api-satellites.rst b/docs/api-satellites.rst deleted file mode 100644 index a5e5113..0000000 --- a/docs/api-satellites.rst +++ /dev/null @@ -1,25 +0,0 @@ -Satellites -========== - -The ``satellites`` method of the :doc:`SatNOGS DB API ` returns all Satellites currently used for gathering Transmitters data. - -Endpoint --------- - - ``https://db.satnogs.org/api/satellites/`` - -Examples --------- - -Show a specific satellite using its Norad Cat ID: - - Request:: - - /api/satellites/25544/?format=json - - Response:: - - { - norad_cat_id": 25544, - "name": "ISS (ZARYA)" - } diff --git a/docs/api-transmitters.rst b/docs/api-transmitters.rst deleted file mode 100644 index 9f69484..0000000 --- a/docs/api-transmitters.rst +++ /dev/null @@ -1,65 +0,0 @@ -Transmitters -============ - -The ``transmitters`` method of the :doc:`SatNOGS DB API ` returns all Transmitters data. - -Endpoint --------- - - ``https://db.satnogs.org/api/transmitters/`` - -Parameters ----------- - - ``mode`` - *Optional* **string** - Returns only transmitters with matching mode - - ``satellite__norad_cat_id`` - *Optional* **string** - Returns only transmitters for the matching satellite - -Examples --------- - -Show transmitters of a satellite with a specific Norad Cat ID: - - Request:: - - /api/transmitters/?format=json&satellite__norad_cat_id=23439 - - Response:: - - { - "uuid": "ybJ86zjXzQxDReZ5skY56B", - "description": "Mode H TLM", - "alive": true, - "uplink_low": null, - "uplink_high": null, - "downlink_low": 29352000, - "downlink_high": null, - "mode": "", - "invert": true, - "baud": 0, - "norad_cat_id": 23439 - } - -Show transmitters of a specific mode: - - Request:: - - /api/transmitters/?format=json&mode=AFSK - - Response:: - - { - "uuid": "4Yp5mRhdNPURqAuVn77NMk", - "description": "Mode V/V AFSK Packet", - "alive": true, - "uplink_low": 145990000, - "uplink_high": null, - "downlink_low": 145800000, - "downlink_high": null, - "mode": "AFSK", - "invert": true, - "baud": 0, - "norad_cat_id": 25544 - } diff --git a/docs/api.rst b/docs/api.rst index b04cba1..887d489 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,18 +1,26 @@ API === -SatNOGS-DB API is a REST API that provides detailed information about Satellites and Transmitters. This document explains how to use the API to retrieve data for your application. +SatNOGS DB API is a REST API that provides detailed information about Satellites and Transmitters. +This document explains how to use the API to retrieve data for your application. + Using API Data -------------- -API access is public to anyone. No form of authentication is required. All API data are freely distributed under the `CC BY-SA `_ license. +API access is open to anyone. +All API data are freely distributed under the `CC BY-SA `_ license. -API Methods ------------ -.. toctree:: - :maxdepth: 1 +Python API Client +----------------- - api-satellites - api-transmitters +A Python client package is automatically generated for each release. +The package is named ``satnogs-db-api-client``. +This Python client is available in `PyPI `_. + + +API Reference +------------- + +`SatNOGS DB API and SDK Documentation <_static/api/index.html>`_ contains a full reference of the API. diff --git a/satnogs-db-api-client/openapi-generator-config.json b/satnogs-db-api-client/openapi-generator-config.json index d64c826..016cbd0 100644 --- a/satnogs-db-api-client/openapi-generator-config.json +++ b/satnogs-db-api-client/openapi-generator-config.json @@ -1,5 +1,15 @@ { "packageName": "satnogsdbapiclient", "projectName": "satnogs-db-api-client", - "generateSourceCodeOnly": true + "generateSourceCodeOnly": true, + "appName": "SatNOGS DB", + "appDescription": "SatNOGS DB is a transmitter suggestions and crowd-sourcing app.", + "infoUrl": "https://gitlab.com/librespacefoundation/satnogs/satnogs-db", + "infoEmail": "dev@satnogs.org", + "invokerPackage": "satnogsdbapiclient", + "perlModuleName": "satnogsdbapiclient", + "phpInvokerPackage": "satnogsdbapiclient", + "pythonPackageName": "satnogsdbapiclient", + "licenseInfo": "Copyright (C) 2020 Libre Space Foundation ", + "licenseUrl": "https://www.gnu.org/licenses/agpl-3.0.html" }