Document query parameters directly instead of via freeform text blurbs #804
Conversation
There was no change to `main.txt` because this version of FastAPI already _happened_ to be "frozen" in there. Reference: https://fastapi.tiangolo.com/tutorial/query-param-models/
I don't think the author of the page intended for it to be fetched by API clients.
This involved refactoring the collection name validation code. When the `@router.get` decoration included the `dependencies` kwarg, the path parameter's description (defined in the function signature) would not appear on Swagger UI. An alternative approach _may_ have been to move the parameter's description (and its other annotations) up to the `dependencies` kwarg (I did not try this). Since I removed the `dependencies` kwarg, I implemented the same logic within the endpoint's request handler function, itself.
|
Hi @dwinston, in case you review this PR branch and have time to address any of the |
|
According to the ticket for the next NMDC Release, code destined for that release is due in |
…lurbs-into-parameter-annotations
|
I'm planning to merge this in on Thursday afternoon. Monday is the date on which we'll be freezing "what's in the dev environment" so team members can begin testing the code that will be included in the upcoming release. |
…ng code
No one uses these endpoints in their still-incomplete form. From the prod analytics (since 2023-10-05):
> db.getCollection("_runtime.analytics").countDocuments({"path": {"$regex": "^/pipeline_search"}}
0
So, remove this cruft.
This endpoint played a role early on in NMDC for a workflow for metadata import. That workflow is no longer used.
No use since 2023-10-05:
> db.getCollection("_runtime.analytics").countDocuments({"path": {"$regex": "^/metadata/json:validate_urls_file"}})
0
|
Thank you, @dwinston, for addressing so many of the |
|
Thanks again, @dwinston. Merging into |
eecavanna
deleted the
665B-convert-swagger-tag-metadata-freeform-blurbs-into-parameter-annotations
branch
In this branch, I effectively relocated the parameter-level documentation from the freeform blurbs atop two endpoint groups on Swagger UI, to the endpoints themselves in Swagger UI. That applies to the endpoints in the "find" section of the Swagger UI, and the endpoints whose paths begin with
/nmdcschema/in the "metadata" section of Swagger UI.Details
The main challenge here was figuring out how to properly mix and match FastAPI's and Pydantic's abstractions in order to get descriptions of Pydantic model attributes to appear next to the corresponding parameter fields on the Swagger UI page. There seem to me to be some unresolved upstream issues at the intersection of those three things:
In this PR branch, I landed on an approach that works for the
descriptionfield, specifically. It does not work for thetitleandexamplesfields. In my local experimentation, I was able to get something to work for all fields, but it involved converting the Pydantic models into regular Python classes (that don't inherit from Pydantic'sBaseModelclass) and that was more of a deviation from the current state of things than I wanted to do in a documentation-focused PR.I also added lots of
TODOcomments about adding documentation to functions that lack it (I just did so for functions I dealt with while working on this PR).<soapbox>I think a given piece of code is generally read more times than it is written (i.e. >1 versus 1), spending time deciphering code can take time/energy, and I think the person writing the code is generally best positioned to document their expectations about whatever it is they are implementing</soapbox>, so I plan to create a ticket(s) about the ones of these I think will be most impactful and assign them to the author(s) of those pieces of code.Finally, here's a screenshot showing query parameter documentation appearing next to the parameters being described. Previously, those query parameters were documented in a freeform text blurb above that group of "metadata" endpoints. The difference shown in this screenshot is representative of the way documentation has changed for many endpoints in this PR branch.
Related issue(s)
Fixes #665
Contributes to microbiomedata/docs#24
Related subsystem(s)
docsdirectory)Testing
I confirmed all the tests performed by the GitHub Actions workflows still pass.
Documentation
docsdirectory)Maintainability
study_id: str)# TODOor# FIXMEblackto format all the Python files I created/modified