From b25e099576c5bf06ca1310d5c73c6741eb3aa8bc Mon Sep 17 00:00:00 2001
From: voetberg <magpie127@gmail.com>
Date: Thu, 20 Nov 2025 09:58:32 -0600
Subject: [PATCH 1/2] Generate Enumerates in schema for docs

---
 tools/run_in_docker/generate_rest_api_docs.py | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/tools/run_in_docker/generate_rest_api_docs.py b/tools/run_in_docker/generate_rest_api_docs.py
index 31ac28d28aa..3b7a21bc6e5 100644
--- a/tools/run_in_docker/generate_rest_api_docs.py
+++ b/tools/run_in_docker/generate_rest_api_docs.py
@@ -89,6 +89,24 @@
 """
 
 
+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: 
+                pass
+
+    return enum_specs
+
 spec = APISpec(
     title="Rucio",
     version=VERSION_INFO["version"],
@@ -116,6 +134,7 @@
                 "description": "The Rucio Token obtained by one of the /auth endpoints.",  # noqa: E501
             },
         },
+        "schemas": collect_enums()
     },
     security=[{"AuthToken": []}],
 )

From be8886cc0c71588a0d2aad00f0928d02c7d1e35b Mon Sep 17 00:00:00 2001
From: voetberg <magpie127@gmail.com>
Date: Thu, 20 Nov 2025 10:15:44 -0600
Subject: [PATCH 2/2] Add instructions for adding enumerate types

---
 docs/developer/rest_api_doc.md                | 21 +++++++++++++++
 tools/run_in_docker/generate_rest_api_docs.py | 26 +++++++++----------
 2 files changed, 34 insertions(+), 13 deletions(-)

diff --git a/docs/developer/rest_api_doc.md b/docs/developer/rest_api_doc.md
index cc29b8b177f..1da392f7edf 100644
--- a/docs/developer/rest_api_doc.md
+++ b/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)
\ No newline at end of file
diff --git a/tools/run_in_docker/generate_rest_api_docs.py b/tools/run_in_docker/generate_rest_api_docs.py
index 3b7a21bc6e5..e522019070a 100644
--- a/tools/run_in_docker/generate_rest_api_docs.py
+++ b/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": []}],
 )