Crafting Clear FastAPI Docstrings for OpenAPI: A Human-Centered Approach

When building APIs with FastAPI, it’s easy to focus entirely on functionality and forget the importance of good documentation. Yet, the quality of your OpenAPI documentation often determines how easily other developers — or even your future self — can understand and use your API. FastAPI automatically uses your function’s docstring to generate OpenAPI documentation, making it crucial to write them with care.

This article outlines a simple, readable, and consistent approach to writing docstrings that make your FastAPI endpoints more understandable and useful, without overwhelming users with technical clutter.

The Structure of a Good OpenAPI Docstring

A well-formed docstring for FastAPI OpenAPI should follow this structure:

Summary paragraph (1–3 sentences): A concise explanation of what the endpoint does.
Optional detailed explanation: Additional context, behaviors, or background described in one or more paragraphs.
No technical boilerplate: Avoid listing arguments, return values, or exception details — these are not shown in OpenAPI UI and are better handled via type hints.

All lines should be wrapped to a maximum of 80 characters to preserve readability across tooling and editors.

Writing the Summary

Start with a clear and brief summary. This line will appear prominently in the autogenerated OpenAPI schema as the endpoint’s title. For example:

python

"""Creates a new user account using the submitted registration data."""

The summary should answer the question: What does this endpoint do? Avoid jargon and implementation details.

Adding a Detailed Explanation

After the summary, you can include more detailed paragraphs that explain:

What kind of request the endpoint handles
What the client is expected to send
What happens behind the scenes (in simple, non-technical terms)
Any conditions or behaviors worth noting

For example:

python
"""Creates a new user account using the submitted registration data.

The request must contain user details such as email, password, and
optionally profile information. If the email is already associated with
an account, the request is rejected.

This endpoint ensures that all sensitive information is securely stored,
and responses are standardized to indicate success or failure.
"""

By writing in plain English and emphasizing the behavior from the user’s point of view, your documentation becomes more approachable and helpful.

Keep It Human, Keep It Readable

Your API documentation may be read by backend engineers, frontend developers, testers, or even non-technical product managers. Avoid code references, avoid assumptions, and format everything for readability:

Wrap text to 80 characters
Separate paragraphs with blank lines
Keep explanations high-level

Boosting Productivity with GitHub Copilot (VS Code)

To streamline writing these docstrings, consider using GitHub Copilot’s VS Code Edit Agent feature. This can drastically reduce the time spent crafting good documentation while maintaining consistency.

Suggested Prompt for Copilot Edit Agent

Here’s a prompt you can give to Copilot’s inline edit command:

Write a human-readable docstring for FastAPI OpenAPI. Start with a short summary of what the endpoint does. Then, add one or more paragraphs explaining the behavior in plain English. Do not mention parameters or return types. Limit each line to 80 characters.

Use this prompt with the Edit with Copilot feature when selecting a FastAPI endpoint method. Copilot will take the function body into account and generate a fitting docstring following the structure outlined in this article.

Final Thoughts

Great developer experience starts with great communication. By writing docstrings that are thoughtful, structured, and user-oriented, you empower anyone who works with your API to understand it faster and use it with confidence.

And with tools like GitHub Copilot, you can combine human intention with AI-assisted speed to produce documentation that speaks clearly and consistently.

Let your documentation work for your team — not against it.