Skip to content

Commit 335f011

Browse files
mislavmislav
committed
Add more examples to api docs
- 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 where applicable
1 parent f43fb26 commit 335f011

File tree

1 file changed

+48
-32
lines changed

1 file changed

+48
-32
lines changed

‎pkg/cmd/api/api.go‎

Lines changed: 48 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -55,44 +55,57 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
5555
cmd := &cobra.Command{
5656
Use: "api <endpoint>",
5757
Short: "Make an authenticated GitHub API request",
58-
Long: `Makes an authenticated HTTP request to the GitHub API and prints the response.
58+
Long: heredoc.Docf(`
59+
Makes an authenticated HTTP request to the GitHub API and prints the response.
5960
60-
The endpoint argument should either be a path of a GitHub API v3 endpoint, or
61-
"graphql" to access the GitHub API v4.
61+
The endpoint argument should either be a path of a GitHub API v3 endpoint, or
62+
"graphql" to access the GitHub API v4.
6263
63-
Placeholder values ":owner", ":repo", and ":branch" in the endpoint argument will
64-
get replaced with values from the repository of the current directory.
64+
Placeholder values ":owner", ":repo", and ":branch" in the endpoint argument will
65+
get replaced with values from the repository of the current directory.
6566
66-
The default HTTP request method is "GET" normally and "POST" if any parameters
67-
were added. Override the method with '--method'.
67+
The default HTTP request method is "GET" normally and "POST" if any parameters
68+
were added. Override the method with %[1]s--method%[1]s.
6869
69-
Pass one or more '--raw-field' values in "key=value" format to add
70-
JSON-encoded string parameters to the POST body.
70+
Pass one or more %[1]s--raw-field%[1]s values in "key=value" format to add
71+
JSON-encoded string parameters to the POST body.
7172
72-
The '--field' flag behaves like '--raw-field' with magic type conversion based
73-
on the format of the value:
73+
The %[1]s--field%[1]s flag behaves like %[1]s--raw-field%[1]s with magic type conversion based
74+
on the format of the value:
7475
75-
- literal values "true", "false", "null", and integer numbers get converted to
76-
appropriate JSON types;
77-
- placeholder values ":owner", ":repo", and ":branch" get populated with values
78-
from the repository of the current directory;
79-
- if the value starts with "@", the rest of the value is interpreted as a
80-
filename to read the value from. Pass "-" to read from standard input.
76+
- literal values "true", "false", "null", and integer numbers get converted to
77+
appropriate JSON types;
78+
- placeholder values ":owner", ":repo", and ":branch" get populated with values
79+
from the repository of the current directory;
80+
- if the value starts with "@", the rest of the value is interpreted as a
81+
filename to read the value from. Pass "-" to read from standard input.
8182
82-
For GraphQL requests, all fields other than "query" and "operationName" are
83-
interpreted as GraphQL variables.
83+
For GraphQL requests, all fields other than "query" and "operationName" are
84+
interpreted as GraphQL variables.
8485
85-
Raw request body may be passed from the outside via a file specified by '--input'.
86-
Pass "-" to read from standard input. In this mode, parameters specified via
87-
'--field' flags are serialized into URL query parameters.
86+
Raw request body may be passed from the outside via a file specified by %[1]s--input%[1]s.
87+
Pass "-" to read from standard input. In this mode, parameters specified via
88+
%[1]s--field%[1]s flags are serialized into URL query parameters.
8889
89-
In '--paginate' mode, all pages of results will sequentially be requested until
90-
there are no more pages of results. For GraphQL requests, this requires that the
91-
original query accepts an '$endCursor: String' variable and that it fetches the
92-
'pageInfo{ hasNextPage, endCursor }' set of fields from a collection.`,
90+
In %[1]s--paginate%[1]s mode, all pages of results will sequentially be requested until
91+
there are no more pages of results. For GraphQL requests, this requires that the
92+
original query accepts an %[1]s$endCursor: String%[1]s variable and that it fetches the
93+
%[1]spageInfo{ hasNextPage, endCursor }%[1]s set of fields from a collection.
94+
`, "`"),
9395
Example: heredoc.Doc(`
96+
# list releases in the current repository
9497
$ gh api repos/:owner/:repo/releases
9598
99+
# post an issue comment
100+
$ gh api repos/:owner/:repo/issues/123/comments -f body='Hi from CLI'
101+
102+
# add parameters to a GET request
103+
$ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'
104+
105+
# set a custom HTTP header
106+
$ gh api -H 'Accept: application/vnd.github.XYZ-preview+json' ...
107+
108+
# list releases with GraphQL
96109
$ gh api graphql -F owner=':owner' -F name=':repo' -f query='
97110
query($name: String!, $owner: String!) {
98111
repository(owner: $owner, name: $name) {
@@ -103,6 +116,7 @@ original query accepts an '$endCursor: String' variable and that it fetches the
103116
}
104117
'
105118
119+
# list all repositories for a user
106120
$ gh api graphql --paginate -f query='
107121
query($endCursor: String) {
108122
viewer {
@@ -119,9 +133,11 @@ original query accepts an '$endCursor: String' variable and that it fetches the
119133
`),
120134
Annotations: map[string]string{
121135
"help:environment": heredoc.Doc(`
122-
GH_TOKEN, GITHUB_TOKEN (in order of precedence): an authentication token for github.com API requests.
136+
GH_TOKEN, GITHUB_TOKEN (in order of precedence): an authentication token for
137+
github.com API requests.
123138
124-
GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN (in order of precedence): an authentication token for API requests to GitHub Enterprise.
139+
GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN (in order of precedence): an
140+
authentication token for API requests to GitHub Enterprise.
125141
126142
GH_HOST: make the request to a GitHub host other than github.com.
127143
`),
@@ -153,12 +169,12 @@ original query accepts an '$endCursor: String' variable and that it fetches the
153169

154170
cmd.Flags().StringVar(&opts.Hostname, "hostname", "", "The GitHub hostname for the request (default \"github.com\")")
155171
cmd.Flags().StringVarP(&opts.RequestMethod, "method", "X", "GET", "The HTTP method for the request")
156-
cmd.Flags().StringArrayVarP(&opts.MagicFields, "field", "F", nil, "Add a parameter of inferred type")
157-
cmd.Flags().StringArrayVarP(&opts.RawFields, "raw-field", "f", nil, "Add a string parameter")
158-
cmd.Flags().StringArrayVarP(&opts.RequestHeaders, "header", "H", nil, "Add an additional HTTP request header")
172+
cmd.Flags().StringArrayVarP(&opts.MagicFields, "field", "F", nil, "Add a typed parameter in `key=value` format")
173+
cmd.Flags().StringArrayVarP(&opts.RawFields, "raw-field", "f", nil, "Add a string parameter in `key=value` format")
174+
cmd.Flags().StringArrayVarP(&opts.RequestHeaders, "header", "H", nil, "Add a HTTP request header in `key:value` format")
159175
cmd.Flags().BoolVarP(&opts.ShowResponseHeaders, "include", "i", false, "Include HTTP response headers in the output")
160176
cmd.Flags().BoolVar(&opts.Paginate, "paginate", false, "Make additional HTTP requests to fetch all pages of results")
161-
cmd.Flags().StringVar(&opts.RequestInputFile, "input", "", "The file to use as body for the HTTP request")
177+
cmd.Flags().StringVar(&opts.RequestInputFile, "input", "", "The `file` to use as body for the HTTP request")
162178
cmd.Flags().BoolVar(&opts.Silent, "silent", false, "Do not print the response body")
163179
return cmd
164180
}

0 commit comments

Comments
 (0)