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 526ac6bff19..e522019070a 100644 --- a/tools/run_in_docker/generate_rest_api_docs.py +++ b/tools/run_in_docker/generate_rest_api_docs.py @@ -13,8 +13,12 @@ # 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.db.sqla import constants from rucio.vcsversion import VERSION from rucio.web.rest.flaskapi.v1.main import application @@ -89,6 +93,20 @@ """ +def collect_enums() -> dict: + """Create a dictionary of all the enumerate types that can be used for spec API docs""" + enum_specs = {} + + for k, v in constants.__dict__.items(): + 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, @@ -116,6 +134,7 @@ "description": "The Rucio Token obtained by one of the /auth endpoints.", # noqa: E501 }, }, + "schemas": collect_enums(), }, security=[{"AuthToken": []}], )