I am excited to show you how to generate Java code for an API based on a Swagger API description.
We will use Swaggerhub, which is what I call an integrated design environment for APIs. You have all the tools for working with API designs in one place! It is focused on Swagger, one of the most popular API description languages.
Now you must be dying to see this all in action.
Check out the video below for a demo of Swaggerhub. In this video, I show you how to use the IDE. I define a demo API, I generate JAX-RS Java code for the API, run the generated API server and finally call the API.
Now, let me tell you why I love designing and developing APIs with API description languages in general.
Swaggerhub is focused on one API description language: Swagger. But no matter if you use Swagger or any of the other common API description languages such as RAML or API Blueprint, they all offer more or less the same benefits. They allow you to follow a contract-first design approach when creating APIs, without losing agility. API description languages allow for very quick feedback loops with the API consumers. At the same time, they allow for architecting the important RESTful characteristics of the API without implementing the API. But even when it comes to implementation, the API description has its advantages: It supports code generation of the API server in the language of your choice. And it even supports the generation of the API clients.
API description languages are used throughout the API life cycle, they are the red thread throughout the life of an API: from the time the API is defined, designed, discussed and reviewed — to when it is implemented and tested and finally documented and used by the API consumers. The API description language supports every step of design, development, operations, and maintenance of the API.
Tools are super important when working with API descriptions, they make it possible to put an API Architecture into practice. Now, all these tools should be integrated for smooth development, so the complete API lifecycle is supported.
Swaggerhub supports each step of the API lifecycle by a dedicated tool:
- An editor with syntax highlighting for sketching, drafting and designing the API.
- A functionality to share your API designs, so you can collaborate with team members.
- A repository for managing the versions of the API.
- A HTML documentation generator that renders a beautiful, interactive API documentation.
- A code generator for producing a code skeleton of an API, which adheres to the design specified in the Swagger file.
- A code generator for producing API clients for any commonly used programming language.
But don’t forget: Swaggerhub is just a tool. It is not sufficient to replace your overall API architecture. If you are serious about using Swagger for large-scale API development, I recommend a two-step approach:
First: Set up your overall API architecture including solution architecture, technical architecture and API platform, API portfolio architecture and RESTful API proxy architecture.
Second: Use tooling such as Swaggerhub for putting your API architecture into practice. It will make it possible and efficient to design your APIs in an agile way.
