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

@@ -13,9 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from enum import Enum
+from inspect import isclass
+
 from apispec import APISpec
 from apispec_webframeworks.flask import FlaskPlugin
-from rucio.vcsversion import VERSION_INFO
+from rucio.db.sqla import constants
+from rucio.vcsversion import VERSION
 from rucio.web.rest.flaskapi.v1.main import application
 
 description_text = """Each resource can be accessed or modified using specially
@@ -89,27 +93,23 @@
 """
 
 
-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 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: 
+        if isclass(v) and issubclass(v, Enum):
+            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"],
+    version=VERSION,
     openapi_version="3.0.2",
     plugins=[FlaskPlugin()],
     info={
@@ -134,7 +134,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": []}],
 )