OpenAPI (known as Swagger before) is a standard to declare Restful API.
But why should I use it?
In the current context, when we are working with APIs (no matters of the language used) we want to have a clean documentation and be able to share a complete documentation of the API to our consumers.
With OpenAPI, you will be able to describe
- all the exposed routes
- all the operations for each route
- the headers
- the body
- all the responses which can be returned and add a lot of details like the kind of each values, some example, some regex which must match, enumeration of value allowed...
And with the swagger editor or some plugins (Swagger UI, you add show it properly to allow non technical people to read it easily!
Ok it's great for consumers, but as a dev is there other pros?
Yes!
Code Generator
With an OpenAPI contract you can generate some code for you!
For your consumer, it will be all the objects in your bodies or responses.
For you, it will be the same objects and some code generator can create for you all the controllers.
You can use the Swagger CodeGen or search in the OpenSource OpenAPI generators.
With this a lot of time is saved, especially if you have a lot of objects and/or if you update them regularly.
Testing
Otherwise, it will be useful for testing. OpenAPI is a standard supported by tools like Postman which will generate for you a collection to be able to call every operations listed in!
Also it will fill every headers and field in the body with the default values.
To conclude, OpenAPI is a must have for a Restful API project. We will see later how to use it!
I hope it will help you! 🍺
Links
- OpenAPI : https://swagger.io/
- OpenAPI Specification : https://swagger.io/specification/
- Swagger Editor : https://editor.swagger.io/
- Swagger UI : https://swagger.io/tools/swagger-ui/
- Swagger CodeGen : https://swagger.io/tools/swagger-codegen/
Top comments (0)