The API reference docs: Are yours complete?

The largest and most important part of the reference documentation is the section that describes all of the API endpoints.

You're probably aware that certain frameworks are available to generate the reference entries for you. Don't assume that you can ignore the reference content.

Here's why:

API Reference docs that are generated from a spec or "from the code" (as we're frequently told) are derived from comments in the spec or the code. Those comments have to be written by somebody, and they are prone to the same errors and omissions as any other documentation. Reviewing (or writing) them requires familiarity with the type of spec (more about OpenAPI specs later), and it also requires a grasp of the information that should be included in the docs.
Occasionally, you might document a new or very small API by writing out the reference content. I've worked on at least four APIS that were documented this way, because the developers weren't generating the reference docs and didn't want to start. You should avoid writing all the content out, if at all possible; however, knowing how to do it means you have mastered the reference section -- and it just might be necessary.
The completeness of the reference section is critical to the success of an API. When developers are asked what they like or hate about APIS, it's often the documentation. And when they hate the documentation, the problem is usually incompleteness. Most developers think their API documentation is pretty good, usually because they are thorough and meticulous about providing all the details. (And they're most likely right.) Here's the thing: The degree of perfection required to keep customers happy is extremely perfect. When customers have a bad experience with the API docs, they're dealing with the one section among dozens or hundreds that is incomplete. And as the hours tick painfully by, they no longer care about the hundreds of entries that were correct. It's like hitting a massive pothole on a blacktop road that causes a flat tire -- you don't spend even a second thinking about how great the rest of the road was.

If there's any lesson to take away about API reference, it's that they must be 100 percent complete and accurate, because users won't accept any less.

What does an endpoint reference entry contain?

Any reference document is a collection of entries structured in a consistent way. Each endpoint should provide the same data as every other, and each entry should be organized in the same way as the others. So if the parameters are in alphabetical order for the first entry, remember to do that for every entry thereafter, unless you have some other system for organizing the parameters, like the order they would appear in a response body.

Here are the elements that should be included in every REST API reference entry.

Name: It helps to give the endpoint some name other than its URL.
Description: A description of the endpoint in question (What is it for, and what can it do?).
HTTP method: The most common are GET, POST, PATCH, PUT, and DELETE.
URL: The distinct address for sending this particular request. If a collection of URLS share a base URL in common, you can describe that at the beginning of your reference section and indicate the unique part of the URL in the reference entry.
Headers: List any HTTP request headers that are required in order for the request to be accepted.
Request parameters: Clearly describe every parameter or property by giving its name, description, and data type. Make sure the description is clear enough that the user knows what they are supposed to use the parameter for. Good names are important, but don't assume that the name makes everything obvious. Indicate whether the parameter is required in order for the request to be accepted. If the parameter has a limited set of possible values, provide all of them and explain how and when to use each.
Response parameters: Just like the request parameters, the response parameters should be fully explained (name, description, data type, required/optional, range of possible values). Users need a description for every parameter returned, to tell them what the data is and how they are expected to use it. Because users are likely to handle the response programmatically, it's important that they know every possible property that might be included in the response and whether those properties are always returned or only returned sometimes.
Example request: Show an example request that is as close as possible to being ready to cut and paste into a terminal. But keep in mind that you need to indicate the user-entered variables.
Explanatory comments (for the request): The comments that follow after any example should explain in plain language what the request is trying to do and point to the important phrases or passages that make things happen. Beyond that, comments also need to help users get unstuck. Many developers get started by modifying the examples, because that's how they learn. They won't come back to read unless they can't make the example work on their own. In those cases, the first place they look is the comments that follow the example. This is why the comments should warn users about common mistakes.
Example response: An example of the response message is just as necessary as the example request. Don't expect readers to be satisfied with only an explanation of HTTP response codes.
Explanatory comments (for the response): The comments following the response example should explain the meaning of whatever data was returned.

(For a reference checklist, see API Reference in my GitHub repo.)

Some other reference topics

In addition to the reference entries that you create for endpoints, the reference documentation must address a few general topics.

The base URL: The domain-level address is general the same for all calls and each endpoint is appended to the base URL. For example, if the domain were HTTPS://paint-drying.com, the base URL for the APIs might be HTTPS://paint-drying/api/. Thus, if the customer-account-creation endpoint has a URL of .../customer, you know that you have to send the request to HTTPS://paint-drying.com/api/customer.
Authentication and Authorization: Most APIs are open only to registered users, so they require some kind of token to complete a call, and you'll have to explain to users how to get one and how to use it.
HTTP response codes: HTTP responses always include an HTTP response code, and users need specific details about what might have gone wrong that resulted in a particular message. The less generic you can make the error information, the better. If the response codes are the same for all endpoints, however, they can be collected in one place rather than repeated in every reference entry.
Throttling (or rate limiting): Users need to know if there is any limit on the number of calls a client can make per second, per hour, per day.