What’s Wrong With OpenAPI?

<p>Are you happy with API documentation in your company? Almost certainly not. We weren&rsquo;t by a long shot.</p> <p>We won&rsquo;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:&nbsp;<strong>developers truly hate describing API</strong>. It&rsquo;s boring and takes ages. Nobody likes wasting their time. Even if you happen to make them do it once, during updates nobody&rsquo;s going back in.</p> <p>Take OpenAPI &mdash; the &ldquo;most convenient&rdquo; language to describe REST API. It&rsquo;s painful to use, a developer will never do it until he absolutely has to (this case&nbsp;perfectly describes the attitude towards OpenAPI).</p> <p>Let&rsquo;s take the simplest API with one endpoint:</p> <pre> GET /users/{id}</pre> <p>Let&rsquo;s say the endpoint responds with a code 200 message like:</p> <pre> { &quot;id&quot;: 123, &quot;name&quot;: &quot;Tom&quot; }</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: &quot;Tom&quot;</pre> <p>Real APIs tend to take not just 23 lines but thousands (here&rsquo;s a&nbsp;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&nbsp;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>