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
Also published on Medium.
