gRPC, JSON, or maybe graphQL? Each method has its advantages, a JSON RESTful API is the simplest, oldest, and most commonly used. However its simplicity comes with a price. Integrating with a REST API requires manually writing client code, which needs to be tested. Tests that tend to become slow since they need to start/stop a web server. Moreover, there are conventions and guidelines for designing RESTful APIs, and once you break one ( include a verb in the path by mistake for example ) and release to production, changing it will require to break backward compatibility, which is never fun. Because of that. Reviewing the designed API before its implemented is an important step in the process. However, writing API docs that can be reviewed manually is tedious, and remembering to update them on every change is a futile effort.

O

penApi formerly known as Swagger attempts to solve those problems and improves the development experience of api users by generating API docs ,clients, and even mock web servers out of an API description file. However, this file quickly becomes immense and complex. Editing it even using the swagger-editor becomes a pain, especially for large projects.

A sub project of the OpenApi initiative, Swagger 2.X Annotations uses reflection to generate OpenApi definitions out of code. Annotated classes, value objects, methods, and parameters are used as input to the swagger generator. The output is a swagger definition file, it can be used then to generate client/server code and API docs. Let’s look at an example.

A Service Definition

• GET /bananas/{id}
• POST /bananas

#annotations #java #swagger #kotlin #openai