add the start of the swagger documentation for the HELICS REST API (#…

…2289)

* add the start of the swagger documentation for the HELICS REST API

* add security schemes fields

* add a few paths to the webserver

* add queries reference for the endpoints

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* change to version 3.0.0 for open API

* Update to add REST swagger doc build vis redoc

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update docs/requirements.txt

Co-authored-by: Ryan Mast <[email protected]>

* Update and retest redoc output

* REST api doc update

* Switch to using custom sphinxcontrib-redoc fork with support for copying entire swagger spec folder

* Add placeholder rest_queries_api.md file so MD parser generates a link to rest_queries_api.html

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix typos in MD rest queries api page placeholder

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Trevor Hardy <[email protected]>
Co-authored-by: Ryan Mast <[email protected]>
Co-authored-by: Ryan Mast <[email protected]>

docs/conf.py

@@ -117,6 +117,7 @@ def ext_candidates(fpath):
     "nbsphinx",
     "IPython.sphinxext.ipython_console_highlighting",
     "breathe",
+    "sphinxcontrib.redoc",
 ]
 
 myst_enable_extensions = [
@@ -170,6 +171,18 @@ def ext_candidates(fpath):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# redoc config
+redoc = [
+    {
+        "name": "HELICS REST API",
+        "page": "references/api-reference/rest_queries_api",
+        "spec-root": "swagger/",
+        "spec": "reference/queries.yaml",
+        "embed": False,
+    }
+]
+
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/references/api-reference/index.md

@@ -16,3 +16,5 @@
 ## [Python API](https://python.helics.org/api/)
 
 ## [Julia API](https://gmlc-tdc.github.io/HELICS.jl/latest/api/)
+
+## [REST Queries API](./rest_queries_api.md)

docs/references/api-reference/rest_queries_api.md

@@ -0,0 +1,3 @@
+# REST Queries API
+
+The latest generated REST Queries API docs can be found at [https://docs.helics.org/en/latest/references/api-reference/rest_queries_api.html](https://docs.helics.org/en/latest/references/api-reference/rest_queries_api.html)

docs/requirements.txt

@@ -7,3 +7,4 @@ nbsphinx==0.8.7
 breathe==4.31.0
 sphinxcontrib-svg2pdfconverter==1.1.1
 requests==2.26.0
+gmlc-tdc-sphinxcontrib-redoc==1.6.1a1

docs/swagger/docs/HELICS-api.md

@@ -0,0 +1,3 @@
+# HELICS-api
+
+The Documentation for the REST API and JSON interfaces for HELICS

docs/swagger/models/BrokerCreation.yaml

@@ -0,0 +1,35 @@
+title: BrokerCreation
+type: object
+properties:
+  type:
+    type: string
+    description: the HELICS core type to use when creating a broker
+  CoreType:
+    type: string
+    description: same as type
+  core_type:
+    type: string
+    description: same as type
+  args:
+    type: string
+    description: extra command line arguments for the broker
+  num_feds:
+    type: number
+  num_brokers:
+    type: number
+  port:
+    type: string
+  host:
+    type: string
+  interface:
+    type: string
+    description: same as host
+  log_level:
+    type: string
+    description: helics logging level to use on the broker
+  uuid:
+    type: string
+    description: the uuid to use for the broker
+  broker_uuid:
+    type: string
+    description: the uuid to use for the broker

docs/swagger/models/CoreConfig.yaml

@@ -0,0 +1,20 @@
+title: CoreConfig
+type: object
+properties:
+  autobroker:
+    type: boolean
+  localport:
+    type: string
+  debugging:
+    type: boolean
+  observer:
+    type: boolean
+  json:
+    type: boolean
+  profiler:
+    type: boolean
+  brokerkey:
+    type: string
+  brokerinitstring:
+    type: string
+description: File configuration for the CoreConfiguration

docs/swagger/models/FederateConfig.yaml

@@ -0,0 +1,3 @@
+title: FederateConfig
+$ref: ""
+description: ""

docs/swagger/models/FederateInfo.yaml

@@ -0,0 +1,60 @@
+title: FederateInfo
+type: object
+properties:
+  name:
+    type: string
+  core:
+    type: string
+  force_new_core:
+    type: boolean
+  coretype:
+    type: string
+  corename:
+    type: string
+  coreinitstring:
+    type: string
+  offset:
+    type:
+      - string
+      - number
+  period:
+    type:
+      - string
+      - number
+  timedelta:
+    type:
+      - string
+      - number
+  rtlag:
+    type:
+      - string
+      - number
+  rtlead:
+    type:
+      - string
+      - number
+  rttolerance:
+    type:
+      - string
+      - number
+  inputdelay:
+    type:
+      - string
+      - number
+  outputdelay:
+    type:
+      - string
+      - number
+  granttimeout:
+    type:
+      - string
+      - number
+  maxiteration:
+    type: integer
+  loglevel:
+    type: string
+  separator:
+    type: string
+  flags:
+    type: string
+description: Properties applying to the federate and its creation

docs/swagger/models/Filter.yaml

@@ -0,0 +1,56 @@
+title: Filter
+description: Configuration for a Filter
+allOf:
+  - type: object
+    properties:
+      name:
+        type: string
+      inputType:
+        type: string
+      outputType:
+        type: string
+      cloning:
+        type: boolean
+      operation:
+        type: string
+      delivery:
+        type: string
+      sourcetargets:
+        type:
+          - string
+          - array
+        items:
+          type: string
+      destinationtargets:
+        type:
+          - string
+          - array
+        items:
+          type: string
+      properties:
+        oneOf:
+          - type: array
+            items:
+              type: object
+              properties:
+                name:
+                  type: string
+                value:
+                  type:
+                    - string
+                    - number
+              required:
+                - name
+                - value
+          - type: object
+            properties:
+              name:
+                type: string
+              value:
+                type:
+                  - string
+                  - number
+            required:
+              - name
+              - value
+  - $ref: ./interfaceOptions.yaml

docs/swagger/models/FilterOptions.yaml

@@ -0,0 +1,14 @@
+title: FilterOptions
+description: Configuration options for a filter
+anyOf:
+  - type: object
+    properties:
+      flags:
+        type:
+          - string
+          - array
+        items:
+          type: string
+      "":
+        type: string
+  - $ref: ./interfaceOptions.yaml

docs/swagger/models/Publication.yaml

@@ -0,0 +1,6 @@
+title: Publication
+type: object
+properties:
+  id:
+    type: string
+description: Configuration for a HELICS publication

docs/swagger/models/address_query.yaml

@@ -0,0 +1,3 @@
+title: address_query
+type: string
+description: return the connection address for the query target

docs/swagger/models/base_response.yaml

@@ -0,0 +1,28 @@
+description: Common information shared across many responses
+type: object
+x-examples:
+  example-1:
+    name: string
+    id: 1
+    parent: 0
+properties:
+  name:
+    type: string
+    minLength: 1
+  uuid:
+    type: string
+    minLength: 1
+    description: If the object is defined as uuid like it will contain the uuid as a field
+  id:
+    type: number
+  parent:
+    type: number
+    description: All objects except root broker will have a parent
+required:
+  - name
+  - id
+examples:
+  - name: string
+    uuid: string
+    id: 0
+    parent: 0

docs/swagger/models/base_status_info.yaml

@@ -0,0 +1,13 @@
+title: base_status_info
+type: object
+properties:
+  id:
+    type: integer
+  "":
+    type: string
+  state:
+    type: string
+required:
+  - id
+  - ""
+  - state

docs/swagger/models/brokers_query.yaml

@@ -0,0 +1,5 @@
+title: brokers_query
+type: array
+description: return a list of the children brokers for a target
+items:
+  type: string

docs/swagger/models/counts_query.yaml

@@ -0,0 +1,36 @@
+description: return counts of the objects and interfaces under an object
+type: object
+x-examples:
+  example-1:
+    name: object_name
+    parent: 1
+    brokers: 3
+    federates: 4
+    countable_federates: 3
+    interfaces: 34
+examples:
+  - name: string
+    id: 1
+    parent: 0
+    brokers: 0
+    federates: 0
+    countable_federates: 0
+    interfaces: 0
+title: ""
+properties:
+  brokers:
+    type: number
+  federates:
+    type: number
+  countable_federates:
+    type: number
+  interfaces:
+    type: number
+  object:
+    $ref: ./base_response.yaml
+required:
+  - brokers
+  - federates
+  - countable_federates
+  - interfaces
+  - object

docs/swagger/models/current_state_query.yaml

@@ -0,0 +1,21 @@
+title: current_state_query
+type: object
+properties:
+  object:
+    $ref: ./base_response.yaml
+  state:
+    type: string
+  status:
+    type: boolean
+  federates:
+    type: array
+    items:
+      $ref: ./base_status_info.yaml
+  cores:
+    type: array
+    items:
+      $ref: ./base_status_info.yaml
+  brokers:
+    type: array
+    items:
+      $ref: ./base_status_info.yaml

docs/swagger/models/current_time_query.yaml

@@ -0,0 +1,5 @@
+title: current_time_query
+type: object
+properties:
+  id:
+    type: string

docs/swagger/models/data_flow_graph_query.yaml

@@ -0,0 +1,17 @@
+title: data_flow_graph_query
+type: object
+properties:
+  object:
+    $ref: ./base_response.yaml
+  brokers:
+    type: array
+    items:
+      $ref: ./data_flow_graph_query.yaml
+  cores:
+    type: array
+    items:
+      $ref: ./data_flow_graph_query.yaml
+  federates:
+    type: array
+    items:
+      $ref: ./data_flow_graph_query.yaml

docs/swagger/models/dependencies_query.yaml

@@ -0,0 +1,13 @@
+title: dependencies_query
+type: object
+properties:
+  object:
+    $ref: ./base_response.yaml
+  dependents:
+    type: array
+    items:
+      type: integer
+  dependencies:
+    type: array
+    items:
+      type: integer