Convert Swagger tag metadata (freeform blurbs) into parameter annotations

[eecavanna]

I volunteered to attempt to transfer the endpoint documentation currently implemented as freeform blurbs for "sections" (i.e. tags) in Swagger UI; into endpoint parameter-specific annotations.

Today, the freeform blurbs are stored in a list variable named tags_metadata in the file nmdc_runtime/api/main.py:

https://github.com/microbiomedata/nmdc-runtime/blob/ac6cf8a76ed54ed9c1f1c303d1b1726e0c9016ad/nmdc_runtime/api/main.py#L71-L292

An example of "parameter-specific annotations" is shown in this issue: https://github.com/microbiomedata/nmdc-runtime/issues/651

[eecavanna]

Some of the tag metadata was copied — at least, partially — from this how-to guide (https://github.com/microbiomedata/NMDC_documentation/blob/main/docs/howto_guides/api_gui.md) via commit 1a9ff23bd97b4a3cabc325b243a6071d189dd8a8.

[eecavanna]

The FindRequest class (which is something that the definitions of find-related parameters are "consolidated" within) is implemented as a Pydantic class. According to https://stackoverflow.com/questions/64364499/set-description-for-query-parameter-in-swagger-doc-using-pydantic-model-fastapi, this can't directly be used to specify an endpoint's parameters in a way that results in Swagger UI showing the parameter metadata. There is a workaround. At this point, I don't know why someone implemented the FindRequest class as a Pydantic class (maybe it was to take advantage of some Pydantic feature).

[ssarrafan]

Moving to next sprint @eecavanna

[eecavanna]

I'll defer this until after the Berkeley Schema Roll Out (unless the Runtime code freeze allows for this type of change via an exception process—TBD).

CC: @aclum

[turbomam]

@eecavanna @ssarrafan

I got an email, in my LBL inbox, that claimed to be a comment on this issue from a user named "levente". It consisted of a suggestion to click on a bit.ly link.

I was tagged as spam by Gmail

Did any of you get that. Does it concern you?

[eecavanna]

Hi @turbomam,

If the username was Klevente12 (which contains the substring, "levente") and the comment date was September 2nd (or a few days before that); I did see a spam comment from that user and reported it to GitHub (the company), who confirmed it violated their terms. Here's an excerpt from the follow-up message I got from GitHub (the company):

Our review of the account named in your report has concluded. We have determined that one or more violations of GitHub’s Terms of Service have occurred and have taken appropriate action in response.

When I see spam comments like that, I (a) refrain from engaging with them and (b) report them to GitHub using the action menu on the comment.

At this point, it's not something I'm worried about (any more than spam on other public forums).

[eecavanna]

These are some web pages (related to this task) I want to preserve links to before I reboot my laptop:

• https://docs.pydantic.dev/latest/concepts/validators/#model-validators
• https://fastapi.tiangolo.com/tutorial/dependencies/classes-as-dependencies/#a-dict-from-the-previous-example