I always wonder why they didn't use Swagger|https://www.openapis.org. It addresses all the key description and security details.