Do I need to write API documentation if I already have OpenAPI?

Usually, yes—but you may need less of it.

An OpenAPI spec is documentation, but it’s mainly machine-readable API documentation. In practice, teams often still need some human-focused docs to fill gaps that OpenAPI doesn’t cover well.

OpenAPI is great for:

• Endpoints, methods, request/response schemas
• Required fields, types, status codes
• Interactive exploration / generated docs
• Client/server code generation

You may still want separate docs for:

• Conceptual overview: what the API is for, how the product fits together
• Authentication and authorization flows: tokens, scopes, login steps
• Business rules: what isn’t obvious from schemas alone
• Usage patterns / examples: common workflows, edge cases
• Error handling guidance: how to recover, retry, rate limits
• Versioning / deprecation policy
• Getting started content for developers

Rule of thumb

• If your API is simple and internal, OpenAPI plus a few usage notes may be enough.
• If your API is public, complex, or developer-facing, you’ll usually need more than OpenAPI alone.

Best practice

Use OpenAPI as the source of truth for the technical contract, and add a developer guide or docs site for the “how to use it effectively” content.

If you want, I can also give you a docs checklist for deciding what to write beyond OpenAPI.