Contribute to the swagger annotation in the source code - generate a good swagger.yaml for docs

Currently, the swagger.yaml (oas.yaml) generated from the source code has been heavily edited for use in generating the API references. The annotations should be updated with the edits, so that the downloaded swagger.yaml can be used to automate the API reference creation.