I have heard the question “Why do I need OpenAPI, Swagger or RAML?” so many times, that I finally decided to sit down and write about it.

Once an API has been designed, it needs to be communicated to team members, developers, product managers, architects, testers and of course to the consumers. API design is often used to communicate between designer and developer or to communicate between provider and consumer. In a sense, the API design serves as a contract.

So the question is: How can I write down my API design? The answer is: API description languages, such as the OpenAPI/Swagger or RAML. They can be used for expressing important aspects of the API design. Especially the frontend design decisions and architectural design decisions, which are visible to the consumer, can be captured by API description languages.

API description languages are also very powerful tools, that can be used for improving the efficiency of design and development through automated generation of design and development artifacts. For example, they can be used for code generation of the API, code generation of the API clients, generation of documentation, generation of tests, and the generation of mocks.

Learn more about API description languages in chapter 4 of the API Design Book, about OpenAPI/Swagger in chapter chapter 8 and about RAML in chapter 9 of the API Design Book.

If you want to focus on Swagger and OpenAPI 2.0, get the Swagger & OpenAPI 2.0 Quick Guide

Why do I need OpenAPI, Swagger or RAML?

Also published on Medium.

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.