Are you happy with API documentation in your company? Almost certainly not. We weren’t by a long shot.
We won’t go into the sad consequences of error-filled, outdated or non-existent API documentation, but why is this seemingly easy-to-solve issue such a big problem on so many projects?
The reason is simple: developers truly hate describing API. It’s boring and takes ages. Nobody likes wasting their time. Even if you happen to make them do it once, during updates nobody’s going back in.
Take OpenAPI — the “most convenient” language to describe REST API. It’s painful to use, a developer will never do it until he absolutely has to (this case perfectly describes the attitude towards OpenAPI).
Let’s take the simplest API with one endpoint:
GET /users/{id}
Let’s say the endpoint responds with a code 200 message like:
{
"id": 123,
"name": "Tom"
}
To achieve it the programmer has to write 23 (!) lines of code in OpenAPI:
openapi: 3.0.1
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema: {}
responses:
200:
content:
application/json:
schema:
required: [id, name]
type: object
properties:
id:
type: integer
example: 123
name:
type: string
example: "Tom"
Real APIs tend to take not just 23 lines but thousands (here’s a 13-thousand-line Twitter API example).
There are, of course, instruments like OpenAPI visual editors, where instead of coding one can use a graphic interface (like https://stoplight.io/), but they are not very helpful: numerous lines of OpenAPI code are replaced with equally numerous mouse clicks.