feat(api): add APIFlask decorators to improve generated API spec doc#857
feat(api): add APIFlask decorators to improve generated API spec doc#857tang-mm wants to merge 11 commits into
Conversation
fix: schemas for file uploads and queue inputs
Update queue endpoints
fix sorting with numeric keys in examples
ajzobro
left a comment
ajzobro
left a comment
There was a problem hiding this comment.
I recognize that this was moved to DRAFT, but I left some comments anyway.
| "tags": ["test", "sample"], | ||
| "provision_data": {"url": "<url>"}, | ||
| "test_data": {"test_cmds": "lsb_release -a"}, | ||
| }, |
There was a problem hiding this comment.
Will need to add missing parameters added since this was drafted.
|
|
||
|
|
||
| class JobInQueueOut(Schema): | ||
| """Job in queue output schema.""" |
There was a problem hiding this comment.
| """Job in queue output schema.""" | |
| """Job (sub-set of job data) for queue output schema.""" |
| keys=fields.String(metadata={"description": "Queue name"}), | ||
| values=fields.Dict( | ||
| keys=fields.String(metadata={"description": "Image name"}), | ||
| values=fields.String( |
There was a problem hiding this comment.
Is this a string, e.g. a URL to an image; or is this binary or otherwise encoded data?
| values=fields.String( | ||
| metadata={"description": "Image provision data"} | ||
| ), | ||
| metadata={"description": "Image data for the queue"}, |
There was a problem hiding this comment.
Based on earlier answer, I think this also needs refinement.
|
|
||
|
|
||
| class ImagePostIn(Schema): | ||
| """Agent image input schema.""" |
There was a problem hiding this comment.
I would discard the word "Agent" and focus on Job or Queue.
| class ClientId(Schema): | ||
| """Client ID input schema.""" | ||
|
|
||
| client_id = fields.String(required=True) |
There was a problem hiding this comment.
Perhaps we should try to disambiguate Agents from Clients and for that matter server clients from "Users"
| class SecretPath(Schema): | ||
| """Secret path schema.""" | ||
|
|
||
| path = fields.String(required=True) |
There was a problem hiding this comment.
There are rules about what makes for a good path, e.g. strings and forward slashes with some numbers, etc. That would be good to capture in an API.
| """Refresh token output schema.""" | ||
|
|
||
| access_token = fields.String(required=True) | ||
| token_type = fields.String(required=True) |
There was a problem hiding this comment.
if the token type will always be "Refresh" we could clarify that here.
| "type": "string" | ||
| }, | ||
| "log": { | ||
| "description": "Push and keep only the last 100 lines", |
There was a problem hiding this comment.
This is no longer accurate.
| }, | ||
| ) | ||
| @v1.input(schemas.ClientId, location="path", arg_name="client_id") | ||
| @v1.auth_required( |
There was a problem hiding this comment.
There are many calls in this code that reference v1.auth_required but there is no such function defined in the current codebase.
2 participants
This PR enhances the Server API documentation using inline docstrings and decorators in
v1.py, following APIFlask pattern. This improves the auto-generated OpenAPI spec with comprehensive documentation.Description
API endpoint documentation migrated from
server/API.mdtov1.py:@v1.inputand@v1.outputdecorators for request/response@v1.doc(responses={...})decorators for non-200 status codesschema.pySchema definition:
Resolved issues
CERTTF-780
Documentation
API.mdis no longer needed/v1/client-permissions, both POST and PUT endpoints were described in the Markdown file, but only PUT is defined in v1.pyWeb service API changes
API docstring and decorators are added or updated, no behavior changes.
Tests
Using the test introduced in #852 :