OpenAPI vs API Documentation
People think OpenAPI is the docs page, and it is not. OpenAPI is one file that lists each path and reply in a fixed shape, so tools can read it. API docs are the guide people read. A docs page is often built from that file, plus words a person wrote.
OpenAPI Specification
One file that lists each path of a REST API and what it sends back.
The OpenAPI Specification is a standard way to describe a REST API in one file. The file is YAML or JSON. It lists every endpoint, what each one takes and what it gives back. Tools read it to make help pages, test the API and write client code. It used to be called Swagger, and many tools still use that name. Writing the file first helps a team agree on an API before coding it.
API Documentation
The guide to an API. It lists each endpoint, what to send and what comes back.
API documentation explains how to use an API. It lists each endpoint, what to send and what comes back. It shows the error codes and what each one means. Good docs have examples you can copy and try. Many are made from an OpenAPI file, so they stay in step with the code.
In one line
- OpenAPI Specification
- One file that lists each path of a REST API and what it sends back.
- API Documentation
- The guide to an API. It lists each endpoint, what to send and what comes back.