Revise API routes docstrings to be useful for OpenAPI docs

[cris-oddball]

User Story - Business Need

API documentation is the contract between VANotify and our clients as to how to utilize API routes. Currently, the docstrings which autogenerate the API spec are more method based, listing the route's arguments, what is raised and what is returned. This is not useful for API documentation. This ticket aims to update all API route docstrings such that they become useful for developers to integrate with our API.

• Ticket is understood, and QA has been contacted (if the ticket has a QA label).

User Story(ies)

As a VANotify developer
I want to revise the docstrings for API routes
So that our API documentation is useful.

As a developer integrating with our API
I want a clearly understandable document
So that I understand how to build out an integration.

Additional Info and Resources

• Medium post on How to document an API for Python FastAPI (downloaded PDF of this is available on request).

• Current view of OpenAPI POST route in ENP
  

• What a better OpenAPI route would look like (from the above blog post)
  

Acceptance Criteria

• The ENP OpenAPI spec no longer informs as to the internal workings of each route but clearly describes the usage of each API route.
• A style guide is posted to the Team Repo and added to its glossary for API docstrings.

QA Considerations

• Review final document for clarity.

Potential Dependencies

Out of Scope

We only want to change the API docstrings, not internal method/class/test docstrings