Add instructions for adding enumerate types

Author: voetberg

docs/developer/rest_api_doc.md

@@ -99,3 +99,24 @@ The OpenAPI Tools are a collection of tools to support writing, verifying and
 displaying Rest API Documentations. They also provide some ideas on how to
 further integrate the documentation into other parts of your code base, e.g. for
 input validation.
+
+### Use Existing Enumerates
+
+If the endpoint requests or returns a common enumerate type, you can use the `schemas` 
+generated from rucio's codebase, such that: 
+```yaml
+ properties:
+    options:
+      description: "..."
+      type: object
+      properties:
+          object1:
+            description: "..."
+            $ref: '#/components/schemas/Object1'
+           object2:
+            description: "..."
+            $ref: '#/components/schemas/Object2'
+
+```
+Where `Object1` and `Object2` can reference any enumerate type in 
+[constants.py](https://github.com/rucio/rucio/blob/master/lib/rucio/db/sqla/constants.py)

tools/run_in_docker/generate_rest_api_docs.py

@@ -89,24 +89,22 @@
 """
 
 
-def collect_enums() -> dict: 
+def collect_enums() -> dict:
     """Create a dictionary of all the enumerate types that can be used for spec API docs"""
     enum_specs = {}
-    from rucio.db.sqla import constants 
+    from rucio.db.sqla import constants
     from inspect import isclass
 
     for k, v in constants.__dict__.items():
         if isclass(v):
-            try: 
-                enum_specs[k] = {
-                    "type": "string",
-                    "enum": [e.value for e in v]
-                }
-            except TypeError: 
+            try:
+                enum_specs[k] = {"type": "string", "enum": [e.value for e in v]}
+            except TypeError:
                 pass
 
     return enum_specs
 
+
 spec = APISpec(
     title="Rucio",
     version=VERSION_INFO["version"],
@@ -134,7 +132,7 @@ def collect_enums() -> dict:
                 "description": "The Rucio Token obtained by one of the /auth endpoints.",  # noqa: E501
             },
         },
-        "schemas": collect_enums()
+        "schemas": collect_enums(),
     },
     security=[{"AuthToken": []}],
 )