One of the most effective ways to leverage LLMs for API documentation is by automating the generation of endpoint descriptions. An endpoint description helps developers understand the functionality of the API, how to use it, and what responses to expect. However, manually writing these descriptions for complex APIs with numerous endpoints can be time-consuming. By leveraging LLMs, automate the generation of API endpoint descriptions, ensuring efficiency without compromising clarity and precision.

In this article, we’ll explore how to use LLMs for automating API endpoint descriptions, along with practical examples of prompts and outputs.

Why automate?

API endpoints define the specific actions that developers can perform, the required parameters, and the expected outputs. A typical endpoint description includes:

– What the endpoint does (e.g., “retrieves a list of users”),

– What HTTP methods it supports (e.g., GET, POST, PUT, DELETE, PATCH),

– What parameters are required or optional,

– The structure of the request and response bodies, and

– Common status codes or errors.

Automating this process with LLMs can significantly reduce the time needed to create documentation, especially for APIs with numerous endpoints. It also ensures that the descriptions are consistent in tone, structure, and detail across the entire API, enhancing the user experience.

How to automate writing endpoint descriptions with LLMs?

Large Language Models such as ChatGPT are trained on vast amounts of text data, including technical documentation. When given structured data such as an OpenAPI specification or Swagger file, LLMs interprets the provided information and generates readable, coherent descriptions for each API endpoint.

For instance, if you have an API specification that defines an endpoint to fetch a list of users, LLMs automatically generates a human-readable explanation of what the endpoint does, which parameters it accepts, and what the expected output is.

Example prompts for generating endpoint descriptions:

When using LLMs to automate endpoint descriptions, the key lies in crafting effective prompts that clearly define the input and expected output. Below are some examples of how you prompt an LLM to generate API endpoint descriptions.

Example 1: Simple API endpoint description:

Let’s start with a basic API that retrieves a list of users. You can use the following prompt:

Basic prompt:

“Write a short description in 100 words about the API endpoint `/users` which can be used with a GET request that returns a list of users. The endpoint accepts an optional query parameter `role` to filter users by their role, and it returns a JSON array with user details such as ID, name, email, and role.”

LLM-generated description:

“The `/users` endpoint retrieves a list of users. This endpoint supports the GET method and returns a JSON array containing user details, including their ID, name, email, and role. You can optionally pass the `role` query parameter to filter the results based on a specific user role (e.g., `admin` or `user`). If the role is not specified, all users will be returned. The response will include an array of user objects with fields: `id` (integer), `name` (string), `email` (string), and `role` (string).”

In this example, the LLM provides a clear and concise description that covers the endpoint’s functionality, HTTP method, parameters, and response structure.

Example 2: API Endpoint with request and response body

For a more complex scenario where the API requires both a request body and a response body, you can structure the prompt accordingly:

More detailed prompt:

“Write a short description (50 words) for the POST endpoint `/users` that allows creating a new user. The request body must include `name`, `email`, and `role`. The response includes the newly created user’s ID, name, email, role, and a timestamp of when the user was created.”

LLM-generated description:

“The `/users` endpoint can be used to add a new user into the database. This endpoint supports the POST method and requires a JSON request body containing the following fields: `name` (string, required), `email` (string, required), and `role` (string, required). The response will return a JSON object with the details of the newly created user, including: `id` (integer), `name` (string), `email` (string), `role` (string), and `created_at` (timestamp), which indicates when the user was created.”

The LLM here captures both the request structure and the expected response, making it easy for developers to understand how to interact with the API.

Example 3: Including error handling

API documentation should also include potential error responses. Ask the LLM to include these in the description itself by creating a prompt accordingly:

Prompt including error handling:

“Write a short description (50) words about the DELETE endpoint `/users/{id}` that deletes a user by their ID. Mention possible error responses like `404 Not Found` if the user doesn’t exist and `403 Forbidden` if the user is not authorized to delete the record.”

LLM-generated description:

“The `/users/{id}` endpoint deletes a user based on their unique ID. This endpoint supports the DELETE method and requires the `id` path parameter to specify the user to be deleted.

On success, the server responds with a `204 No Content` status.

Possible error responses include:

• `404 Not Found` if no user exists with the given ID, and
• `403 Forbidden` if the current user does not have permission to delete the specified record.”

Here, the LLM provides not only the endpoint’s main functionality but also clearly outlines potential error scenarios, helping developers handle edge cases.

Automating API endpoint descriptions with LLMs is a powerful way to streamline the documentation process. By using structured prompts, LLMs generate accurate, concise, and consistent descriptions covering essential details such as HTTP methods, parameters, request/response bodies, and error handling. The automation reduces the manual effort involved in API documentation while maintaining high standards of clarity and precision. However, as with any automated process, human review is essential to ensure the generated content is both accurate and aligned with the API’s intent.

utomate Your API Documentation Today! Discover how LLMs can streamline the process and enhance consistency. Ready to learn more? Start exploring now!