shaba/openuds
1
0
Fork 1
mirror of https://github.com/dkmstr/openuds.git synced 2025-03-20 06:50:23 +03:00
Code Issues Releases Wiki Activity

Refactor HelpMethodInfo and HelpMethod classes for improved API documentation clarity

Browse Source
This commit is contained in:
Adolfo Gómez García 2025-02-03 17:16:33 +01:00
parent 4c59a25092
commit 6899cff246
No known key found for this signature in database
GPG Key ID: DD1ABF20724CDA23
3 changed files with 85 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
server/src/uds/REST/documentation.py
View File

@ -53,36 +53,24 @@ logger = logging.getLogger(__name__)
@dataclasses.dataclass
class HelpMethodInfo:
method: str
params: list[str]
text: str
@property
def methods(self) -> typing.Generator[str, None, None]:
for param in self.params:
if param == '':
yield self.method
else:
if (self.method + ' ')[0] == '-':
yield f'<{param}>/{self.method[1:]}'
elif self.method:
yield f'{self.method}/<{param}>'
else:
yield f'<{param}>'
def __str__(self) -> str:
return ', '.join(self.methods)
return f'{self.method}: {self.text}'
def __repr__(self) -> str:
return self.__str__()
class HelpMethod(enum.Enum):
ITEM = HelpMethodInfo('', ['uuid'], 'Retrieves an item by its UUID')
LOG = HelpMethodInfo('-' + consts.rest.LOG, ['uuid'], 'Retrieves the log of an item')
OVERVIEW = HelpMethodInfo(consts.rest.OVERVIEW, [''], 'General Overview of all items (a list')
TABLEINFO = HelpMethodInfo(consts.rest.TABLEINFO, [''], 'Table visualization information (types, etc..)')
TYPES = HelpMethodInfo(consts.rest.TYPES, ['', 'type'], 'Types information')
GUI = HelpMethodInfo(consts.rest.GUI, ['', 'type'], 'GUI information')
ITEM = HelpMethodInfo('', 'Retrieves an item by its UUID')
LOG = HelpMethodInfo(f'<uuid>/{consts.rest.LOG}', 'Retrieves the log of an item')
OVERVIEW = HelpMethodInfo(consts.rest.OVERVIEW, 'General Overview of all items (a list')
TABLEINFO = HelpMethodInfo(consts.rest.TABLEINFO, 'Table visualization information (types, etc..)')
TYPES = HelpMethodInfo(consts.rest.TYPES, 'Retrieves a list of types available')
TYPES_TYPE = HelpMethodInfo(f'{consts.rest.TYPES}/<type>', 'Retrieves a type information')
GUI = HelpMethodInfo(consts.rest.GUI, 'GUI information')
GUI_TYPES = HelpMethodInfo(f'{consts.rest.GUI}/<type>', 'GUI Types information')
@dataclasses.dataclass
@ -112,13 +100,24 @@ class Documentation(View):
methods = [
HelpMethod.OVERVIEW,
HelpMethod.GUI,
HelpMethod.TABLEINFO,
HelpMethod.GUI_TYPES,
HelpMethod.TYPES,
HelpMethod.TYPES_TYPE,
HelpMethod.TABLEINFO,
HelpMethod.ITEM,
HelpMethod.LOG,
]
elif node.kind == types.rest.HelpNode.HelpNodeType.DETAIL:
methods = []
methods = [
HelpMethod.OVERVIEW,
HelpMethod.GUI,
HelpMethod.GUI_TYPES,
HelpMethod.TYPES,
HelpMethod.TYPES_TYPE,
HelpMethod.TABLEINFO,
HelpMethod.ITEM,
HelpMethod.LOG,
]
else:
methods = []

46
server/src/uds/REST/model/detail.py
View File

@ -144,6 +144,52 @@ class DetailHandler(BaseModelHandler):
r = self._check_is_custom_method(self._args[0], parent)
if r is not consts.rest.NOT_FOUND:
return r
match self._args[0]:
case consts.rest.OVERVIEW:
if num_args == 1:
return self.get_items(parent, None)
raise self.invalid_request_response()
case consts.rest.TYPES:
if num_args == 1:
types_ = self.get_types(parent, None)
logger.debug('Types: %s', types_)
return types_
elif num_args == 2:
return self.get_types(parent, self._args[1])
raise self.invalid_request_response()
case consts.rest.TABLEINFO:
if num_args == 1:
return self.process_table_fields(
self.get_title(parent),
self.get_fields(parent),
self.get_row_style(parent),
)
raise self.invalid_request_response()
case consts.rest.GUI:
if num_args in (1, 2):
if num_args == 1:
gui = self.get_processed_gui(parent, '')
else:
gui = self.get_processed_gui(parent, self._args[1])
return sorted(gui, key=lambda f: f['gui']['order'])
raise self.invalid_request_response()
case consts.rest.LOG:
if num_args == 2:
return self.get_logs(parent, self._args[1])
raise self.invalid_request_response()
case _:
# try to get id
if num_args == 1:
return self.get_items(parent, process_uuid(self._args[0]))
# Maybe a custom method?
r = self._check_is_custom_method(self._args[1], parent, self._args[0])
if r is not None:
return r
# Not understood, fallback, maybe the derived class can understand it
return self.fallback_get()
if num_args == 1:
match self._args[0]:

21
server/src/uds/templates/uds/modern/documentation.html
View File

@ -13,6 +13,20 @@
<link href="/uds/res/modern/fonts/roboto.css" rel="stylesheet" />
<!-- Material styles -->
<link href="/uds/res/modern/styles.css" rel="stylesheet" />
<style>
.doc {
padding: 20px;
}
.doc-item {
margin-bottom: 20px;
}
.doc-item-methods {
margin-left: 20px;
}
.doc-item-method {
margin-bottom: 10px;
}
</style>
</head>
<body>
<div>
@ -31,15 +45,14 @@
{% if h.methods %}
<div class="doc-item-methods">
{% for m in h.methods %}
{% for mm in m.value.methods %}
<div class="doc-item-method">{{ h.path }}/{{ mm }}</div>
{% endfor %}
<div class="doc-item-method">{{ h.path }}/{{ m.value.method }} : {{ m.value.text }}</div>
{% endfor %}
</div>
{% else %}
<div>{{ h.path }} : {{ h.text }}</div>
{% endif %}
</div>
{% endfor %}
</div>
</div>