Finished feature add-swagger-docs.

f729cd1f · Erik Reid · ae001c94 · 5a4480b4 · f729cd1f · f729cd1f
Commit f729cd1f authored 2 years ago by Erik Reid
--- a/docs/dump-openapi-spec.py
+++ b/docs/dump-openapi-spec.py
+import json
+import os
+
+from fastapi.testclient import TestClient
+import resource_management
+
+config_filename = os.path.join(
+    os.path.dirname(__file__),
+    '..', 'config-example.json')
+
+output_filename = os.path.join(
+    os.path.dirname(__file__),
+    'source', '_static', 'openapi.json')
+
+os.environ['SETTINGS_FILENAME'] = config_filename
+app = resource_management.create_app()
+client = TestClient(app)
+rsp = client.get('/openapi.json')
+openapi_doc = json.dumps(rsp.json(), indent=2)
+
+with open(output_filename, 'w') as f:
+    f.write(openapi_doc)
+
+print(f'wrote {output_filename}')
--- a/docs/source/_static/openapi.html
+++ b/docs/source/_static/openapi.html
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta
+    name="description"
+    content="SwaggerUI"
+  />
+  <title>SwaggerUI</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
+<script>
+  window.onload = () => {
+    window.ui = SwaggerUIBundle({
+      url: '_static/openapi.json',
+      dom_id: '#swagger-ui',
+    });
+  };
+</script>
+</body>
+</html>
\ No newline at end of file
--- a/docs/source/basic-tools.rst
+++ b/docs/source/basic-tools.rst
-.. list of basic cli tools
-
-CLI Tools
-=========================
-
-.. automodule:: resource_management.cli
-
-.. automodule:: resource_management.hardware.juniper
--- a/docs/source/images/db-er.png
+++ b/docs/source/images/db-er.png
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,43 +6,15 @@
 NAT Resource Management
 ==========================

-Documentation for the NAT Resource Management tools
-
------------------
-
-Configuration file format
---------------------------------
-
-The following example indicates the schema for the configuration file required to call the Resource Management client::
-
-   {
-         "mysql":{
-                  "username":"mydbuser",
-                  "password":"mydbpass",
-                  "hostname":"localhost",
-                  "dbname":"mydb"
-         },
-         "ssh":{
-                  "username":"user",
-                  "password":"pass",
-                  "private-key":"/path/to/private/key"
-                  "ssh-config":"/path/to/ssh-config"
-         }
-   }
-
-All "mysql" parameters are mandatory. For "ssh", username is mandatory, and either password or private-key must be provided. ssh-config is optional.
-
-Excuting the client
---------------------
-
-To create a new router from its fqdn::
-
-   python3 cli.py create  --config /path/to/resource_management_config.json --fqdn test.example.com
-
+Documentation for the NAT Resource Management service

 .. toctree::
   :maxdepth: 1
   :caption: Contents:

-   basic-tools
+   quickstart
   db
+
+
+`Swagger API Docs <_static/openapi.html>`__
+
--- a/docs/source/quickstart.rst
+++ b/docs/source/quickstart.rst
+.. db model intro & info
+
+
+Quick Start
+==================
+
+
+
+*This is a quick setup guide for running
+standalone on your local machine*
+
+Create a Local Database
+--------------------------
+
+* set the value of `sqlalchemy.url`
+  in `alembic.ini` to point to a writeable file, e.g.
+
+  .. code-block:: python
+
+     sqlalchemy.url = sqlite:////absolute/path/to/foo.db
+
+
+* create the database by running the alembic
+  migration from the module (`resource_management`) directory
+
+  .. code-block:: bash
+
+     alembic upgrade head
+
+Running the App
+-------------------
+
+* create a settings filename
+  (see `config-example.json` for an example) ... something like:
+
+  .. code-block:: json
+
+     {
+       "db": "sqlite:////tmp/test.db",
+       "ssh": {
+         "username": "ro-username",
+         "private-key": "/absolute/path/to/private/key"
+       }
+    }
+
+* run the app like this
+  (`app.py` starts the server on port 44444):
+
+  .. code-block:: bash
+
+     SETTINGS_FILENAME=/absolute/path/to/config.json python -m resource_management.app
+
+Examples
+
+* get the version
+
+  .. code-block:: bash
+
+     curl http://localhost:44444/api/version
+
+* load interfaces from a router
+
+  .. code-block:: bash
+
+     curl -X POST http://localhost:44444/api/initialize-router/router.host.name
+
+* view the docs by loading `http://localhost:44444/docs`
+  in your browser (there are requests for reserving
+  lags and physical lag interfaces)
--- a/tox.ini
+++ b/tox.ini
@@ -18,4 +18,9 @@ commands =
    coverage html
    coverage report --fail-under 80
    flake8
+    python docs/dump-openapi-spec.py
+    # to render the diagrams:
+    #   pip install -r docs/requirements-er.txt
+    #   ... and install dot on the system
+    # python docs/render_db_diagrams.py
    sphinx-build -M html docs/source docs/build