Add more examples to api docs

[mislav]

• Clarify that fields need to be in "key=value" format
• Headers need to be in "key:value" format
• Contrast POST vs GET requests with params in examples
• Add an example of how to add HTTP headers
• Use backticks for denoting inline code

Makes an authenticated HTTP request to the GitHub API and prints the response.

The endpoint argument should either be a path of a GitHub API v3 endpoint, or
"graphql" to access the GitHub API v4.

Placeholder values ":owner", ":repo", and ":branch" in the endpoint argument will
get replaced with values from the repository of the current directory.

The default HTTP request method is "GET" normally and "POST" if any parameters
were added. Override the method with `--method`.

Pass one or more `--raw-field` values in "key=value" format to add
JSON-encoded string parameters to the POST body.

The `--field` flag behaves like `--raw-field` with magic type conversion based
on the format of the value:

- literal values "true", "false", "null", and integer numbers get converted to
  appropriate JSON types;
- placeholder values ":owner", ":repo", and ":branch" get populated with values
  from the repository of the current directory;
- if the value starts with "@", the rest of the value is interpreted as a
  filename to read the value from. Pass "-" to read from standard input.

For GraphQL requests, all fields other than "query" and "operationName" are
interpreted as GraphQL variables.

Raw request body may be passed from the outside via a file specified by `--input`.
Pass "-" to read from standard input. In this mode, parameters specified via
`--field` flags are serialized into URL query parameters.

In `--paginate` mode, all pages of results will sequentially be requested until
there are no more pages of results. For GraphQL requests, this requires that the
original query accepts an `$endCursor: String` variable and that it fetches the
`pageInfo{ hasNextPage, endCursor }` set of fields from a collection.


USAGE
  gh api <endpoint> [flags]

FLAGS
  -F, --field key=value       Add a typed parameter in key=value format
  -H, --header key:value      Add a HTTP request header in key:value format
      --hostname string       The GitHub hostname for the request (default "github.com")
  -i, --include               Include HTTP response headers in the output
      --input file            The file to use as body for the HTTP request
  -X, --method string         The HTTP method for the request (default "GET")
      --paginate              Make additional HTTP requests to fetch all pages of results
  -f, --raw-field key=value   Add a string parameter in key=value format
      --silent                Do not print the response body

INHERITED FLAGS
  --help   Show help for command

EXAMPLES
  # list releases in the current repository
  $ gh api repos/:owner/:repo/releases
  
  # post an issue comment
  $ gh api repos/:owner/:repo/issues/123/comments -f body='Hi from CLI'
  
  # add parameters to a GET request
  $ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'
  
  # set a custom HTTP header
  $ gh api -H 'Accept: application/vnd.github.XYZ-preview+json' ...
  
  # list releases with GraphQL
  $ gh api graphql -F owner=':owner' -F name=':repo' -f query='
    query($name: String!, $owner: String!) {
      repository(owner: $owner, name: $name) {
        releases(last: 3) {
          nodes { tagName }
        }
      }
    }
  '
  
  # list all repositories for a user
  $ gh api graphql --paginate -f query='
    query($endCursor: String) {
      viewer {
        repositories(first: 100, after: $endCursor) {
          nodes { nameWithOwner }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  '

ENVIRONMENT VARIABLES
  GH_TOKEN, GITHUB_TOKEN (in order of precedence): an authentication token for
  github.com API requests.
  
  GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN (in order of precedence): an
  authentication token for API requests to GitHub Enterprise.
  
  GH_HOST: make the request to a GitHub host other than github.com.

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

Ref. #2941, Closes #2948

[samcoe]

I like the changing of single quotes to backticks.