Why Is Swagger JSON Better Than Swagger Java Client?

The Swagger Java-Based Client Using Java Annotations on the Controller layer

Pros and Cons

• It’s the old way of creating web-based REST API documents through the Swagger Java library.
• It’s easy for Java developers to code.
• All API description of endpoints will be added in the Java annotations parameters.
• Swagger API dependency has to be added to the Maven configuration file POM.xml.
• It creates overhead on the performance because of extra processing time for creating Swagger GUI files (CSS, HTML, JS etc). Also, parsing the annotation logic on the controller classes creates overhead on the performance, as well. It makes the build a little heavy to deploy on microservices, where build size should be smaller.
• The code looks dirty because the extra code has to be added to the Spring MVC Controller classes through the Spring annotations. Sometimes, if the description of the API contract is too long, then it makes code unreadable and maintainable.
• Any change in an API contract requires Java to build changes and re-deployment, even if it’s only simple text changes, like API definition text.
• The biggest challenge is to share with the clients/QA/BA teams before the actual development and to make frequent amendments. The service consumers may change their requirements frequently. Then, it’s very difficult to make these changes in code and create the Swagger GUI HTML pages by redeploying and sharing the updated Swagger dashboard on the actual deployed dev/QA env.

2. Swagger JSON File Can be Written Separately and Provide Browser-Based GUI

Pros and Cons

• In this latest approach, all of the above challenges with Java-based client solution have been solved.
• The developer initially creates a JSON file, shares, and agrees with the service consumer and stakeholders. They will get signed off after many amendments —no code change and re-deployment are required.
• The code will be cleaner, readable, and maintainable.
• There is no extra overhead for file creation and processing, performance is better, and the code is more lightweight for microservices, etc.
• There is no code dependency for any API contract changes.
• Swagger JSON file resides in the project binaries (inside src/main/resources/swagger_api_doc.json). We can deploy Swagger on one server and can switch to an environment like this.

Note

You can copy and paste swagger_api_doc.json JSON file content on https://editor.swagger.io/. It will help you modify content and create an HTML page like the following.  Swagger GUI will provide the web-based interface like Postman.