What’s Wrong With OpenAPI?
<p>Are you happy with API documentation in your company? Almost certainly not. We weren’t by a long shot.</p>
<p>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?</p>
<p>The reason is simple: <strong>developers truly hate describing API</strong>. 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.</p>
<p>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).</p>
<p>Let’s take the simplest API with one endpoint:</p>
<pre>
GET /users/{id}</pre>
<p>Let’s say the endpoint responds with a code 200 message like:</p>
<pre>
{
"id": 123,
"name": "Tom"
}</pre>
<p>To achieve it the programmer has to write 23 (!) lines of code in OpenAPI:</p>
<pre>
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"</pre>
<p>Real APIs tend to take not just 23 lines but thousands (here’s a 13-thousand-line Twitter API example).</p>
<p>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.</p>
<p><a href="https://levelup.gitconnected.com/whats-wrong-with-openapi-771e67e2bf6f">Visit Now</a></p>