"Add labels to an issue" code block is badly formatted and missing documentation

[Marcono1234]

What happened?

The code block of addLabels.md is badly formatted (indentation is wrong), and the page is missing documentation.

Though the GitHub docs page is also rather confusing:

• You can pass an empty array to remove all labels.

  Is that actually correct or was it copied from "Set labels for an issue" by accident? It would be rather surprising if an 'add' operation is able to delete something.

• but GitHub recommends passing an object with the labels key

  Not quite sure what "object" means here, the previous sentence said the type is array; same applies to the "Set labels for an issue" endpoint.

• The examples for this endpoint as well as "Set labels for an issue" seem to be copied from "list labels"; they don't actually specify labels to add / set

[gr2m]

The code block of addLabels.md is badly formatted (indentation is wrong),

we should run the code through prettier, as we do here

plugin-rest-endpoint-methods.js/scripts/update-endpoints/code.js

Lines 119 to 130 in f27909a

	writeFileSync(
	ROUTES_PATH,
	prettier.format(
	`import { EndpointsDefaultsAndDecorations } from "../types";
	const Endpoints: EndpointsDefaultsAndDecorations = ${JSON.stringify(
	sortKeys(newRoutes, { deep: true })
	)}
	export default Endpoints`,
	{ parser: "typescript" }
	)
	);

A pull request would be much appreciated

Though the GitHub docs page is also rather confusing

Both the GitHub docs and the code in this repository are generated from GitHub's OpenAPI spec at https://github.com/github/rest-api-description/. That's where the parameter description would need to be fixed.

You can pass an empty array to remove all labels.
Is that actually correct or was it copied from "Set labels for an issue" by accident? It would be rather surprising if an 'add' operation is able to delete something.

I'm with you, it sounds incorrect to me. Can you verify?

Not quite sure what "object" means here, the previous sentence said the type is array; same applies to the "Set labels for an issue" endpoint.

Originally, the POST /repos/{owner}/{repo}/issues/{issue_number}/labels and several others would accept the HTTP request body to be an array, as in ["label1", "label2"]. We changed all these endpoints to also accept { "labels": ["labels1: "labels2"]}, to make the endpoint easier to consume with SDKs such as Octokit.js.

You can basically ignore the whole note.

The examples for this endpoint as well as "Set labels for an issue" seem to be copied from "list labels"; they don't actually specify labels to add / set

My guess here is that the OpenAPI spec defines an anyOf here to account for the different types of request body be accepted. That's why the examples are very useful, because technically the labels parameter is not required.

I'd file an issue for that on github.com/github/docs, if none exists yet. You can mention me there. I'd argue we should no longer document sending labels as array in the request body at all, and remove it entirely from the public OpenAPI spec.