describeREST writes what GitHub's REST description says about a request and the body of one of its responses.
(w io.Writer, idx *restIndex, opts schemaOptions)
| 259 | // describeREST writes what GitHub's REST description says about a request and |
| 260 | // the body of one of its responses. |
| 261 | func describeREST(w io.Writer, idx *restIndex, opts schemaOptions) error { |
| 262 | method, target, _ := strings.Cut(opts.name, " ") |
| 263 | if !strings.HasPrefix(target, "/") { |
| 264 | return fmt.Errorf("%s isn't on the REST API host, so GitHub's REST description doesn't cover it", target) |
| 265 | } |
| 266 | path, _, _ := strings.Cut(target, "?") |
| 267 | route := idx.match(method, path) |
| 268 | if route == nil { |
| 269 | return fmt.Errorf("GitHub's REST description has no path matching %s", path) |
| 270 | } |
| 271 | op := route.item.GetOperation(method) |
| 272 | if op == nil { |
| 273 | return fmt.Errorf("GitHub documents no %s for %s; it documents %s", method, route.template, strings.Join(routeMethods(route.item), ", ")) |
| 274 | } |
| 275 | |
| 276 | fmt.Fprintf(w, "%s %s\n", method, route.template) |
| 277 | switch { |
| 278 | case op.Summary != "" && op.OperationID != "": |
| 279 | fmt.Fprintf(w, "%s (%s)\n", op.Summary, op.OperationID) |
| 280 | case op.Summary != "": |
| 281 | fmt.Fprintln(w, op.Summary) |
| 282 | case op.OperationID != "": |
| 283 | fmt.Fprintln(w, op.OperationID) |
| 284 | } |
| 285 | if op.Deprecated { |
| 286 | fmt.Fprintln(w, "Deprecated.") |
| 287 | } |
| 288 | statuses := documentedStatuses(op.Responses) |
| 289 | if len(statuses) == 0 { |
| 290 | fmt.Fprintln(w, "Documented statuses: none") |
| 291 | return nil |
| 292 | } |
| 293 | fmt.Fprintf(w, "Documented statuses: %s\n", strings.Join(statuses, ", ")) |
| 294 | |
| 295 | status, ref := pickStatus(op.Responses, opts.status, statuses) |
| 296 | if ref == nil { |
| 297 | return fmt.Errorf("GitHub doesn't document status %d for %s %s; it documents %s", |
| 298 | opts.status, method, route.template, strings.Join(statuses, ", ")) |
| 299 | } |
| 300 | var media *openapi3.MediaType |
| 301 | if ref.Value != nil { |
| 302 | media = jsonMedia(ref.Value.Content) |
| 303 | } |
| 304 | if media == nil || media.Schema == nil || media.Schema.Value == nil { |
| 305 | if opts.at != "" { |
| 306 | return fmt.Errorf("status %s has no JSON body", status) |
| 307 | } |
| 308 | fmt.Fprintf(w, "Body for %s: none\n", status) |
| 309 | return nil |
| 310 | } |
| 311 | |
| 312 | schema, err := schemaAt(media.Schema, opts.at) |
| 313 | if err != nil { |
| 314 | return err |
| 315 | } |
| 316 | label := "Body" |
| 317 | if opts.at != "" { |
| 318 | label = opts.at + ", in the body" |
no test coverage detected