docs: improve glab api command docs
Description
This merge request improves the documentation and help text for the GitLab CLI's API command. The changes make the writing clearer and more user-friendly by:
- Restructuring sentences to be more direct and easier to read.
- Adding helpful comments to all the code examples to explain what each command does.
- Breaking up long paragraphs into shorter, more digestible sections.
- Improving the formatting of links and references.
Related issues and merge requests
Documentation
If this MR adds or updates CLI command documentation, follow the conventions in the
GitLab CLI (glab) documentation style guide,
run make gen-docs, and commit the updated files in docs/source/.