In the fast-paced world of software development, effective API documentation is crucial. It helps developers understand how to use your APIs, accelerates integration, and fosters collaboration. In this tech blog, we’ll explore how to generate Swagger documentation from OpenAPI specifications using Java Spring Boot. Swagger is a widely used tool for API documentation, and Spring Boot simplifies the process of building robust APIs.

Audience

This blog post is aimed at:

  • Developers and programmers who want to learn how to generate Swagger documentation for their APIs using Java Spring Boot.
  • Tech enthusiasts looking to improve their API documentation skills.
  • Anyone interested in API development and documentation.

Prerequisites

Before diving into the main content, readers should have a basic understanding of the following:

  • Java programming language.
  • Spring Boot framework.
  • OpenAPI specifications (basic knowledge is sufficient).
  • A development environment setup for Java Spring Boot.

Main Content

Understanding OpenAPI and Swagger

OpenAPI:

OpenAPI is a specification for building APIs that provides a standardized way to describe RESTful APIs. It allows developers to define API endpoints, request/response formats, authentication methods, and more in a machine-readable format. The OpenAPI Specification, often referred to as OAS or simply OpenAPI, uses JSON or YAML to define API contracts. It is vendor-neutral and language-agnostic, making it a widely adopted standard in the world of API development.

Swagger:

Swagger is a set of open-source tools built around the OpenAPI Specification. It includes tools for designing, building, and documenting RESTful APIs. Swagger UI, for instance, is a popular tool for generating interactive documentation from OpenAPI specifications. It allows developers to visualize and test APIs directly from the documentation.

In essence, Swagger is a suite of tools that makes it easier to work with and generate documentation from OpenAPI specifications.

Swagger over postman

Postman and Swagger are both valuable tools in API development, but they serve different purposes, and each has its own set of advantages and disadvantages. Here are some of the disadvantages of using Postman over Swagger:

  1. Limited Documentation: Postman primarily focuses on API testing and doesn’t provide comprehensive documentation capabilities. While it allows you to add descriptions and comments to requests, it doesn’t offer structured API documentation that Swagger does.
  2. Lack of Standardization: Postman doesn’t enforce any standardized format for API documentation. Swagger, on the other hand, follows the OpenAPI Specification (formerly known as Swagger Specification), which provides a common standard for documenting APIs.
  3. No Auto-Generation: Postman doesn’t automatically generate API documentation from code or specifications. You have to manually create and maintain documentation, which can be time-consuming and error-prone.
  4. Limited Collaboration Features: While Postman offers some collaboration features, such as sharing collections, it doesn’t provide the same level of collaboration and version control capabilities as Swagger. Swagger allows multiple team members to collaborate on API design and documentation using tools like Swagger Editor and SwaggerHub.
  5. Less Integration with Code: Postman is primarily a standalone tool for testing APIs, whereas Swagger can be integrated into the development process more deeply. With Swagger, you can generate code stubs, server implementations, and client SDKs directly from the API specification.
  6. Complexity for Large APIs: Postman may become complex and less manageable for large, complex APIs with numerous endpoints. Swagger’s structured documentation is better suited for handling complex API specifications.
  7. Cost Considerations: Postman has a free version, but advanced features and collaboration capabilities often require a paid subscription. Swagger offers both open-source and commercial solutions, so cost considerations may differ depending on your needs.
  8. Limited Mocking: While Postman provides some mock server functionality for simulating API responses, it may not be as feature-rich or customizable as what you can achieve with Swagger tools like SwaggerHub.

It’s worth noting that both Postman and Swagger have their strengths, and the choice between them depends on your specific requirements. Postman is excellent for API testing, while Swagger excels at API documentation, design, and code generation. In many cases, developers use both tools in conjunction to cover the entire API development lifecycle, from design and testing to documentation and deployment.

Setting Up a Spring Boot Project

Step 1: Adding SpringDoc Dependency

To get started, add the SpringDoc dependency to your project. You can do this by including the following line in your build.gradle or pom.xml:

image 5 Building Swagger Documentation with Java Spring Boot Using OpenAPI

This dependency provides the necessary tools for generating interactive API documentation.

Step 2: Create a Controller

Next, create a controller that will redirect requests to the Swagger UI. You can do this by adding the following code to a new or existing controller:

image 7 Building Swagger Documentation with Java Spring Boot Using OpenAPI

In this controller, the redirectToSwagger method redirects requests to the Swagger UI, and the openApiDefinition method returns the OpenAPI text. Be sure to customize the openApiDefinition method with your API documentation.

Step 3: Configure Application Properties

To fine-tune SpringDoc’s behavior, you can configure some properties in your application.properties file. Add the following properties to disable the default Swagger UI provided by SpringDoc:

image 6 Building Swagger Documentation with Java Spring Boot Using OpenAPI

These properties will ensure that the default Swagger UI is disabled and that the Swagger UI is accessible at the /swagger-ui/index.html endpoint.

In Yubi: Growing Popularity of Swagger in the Colending Team

In the Colending team, we used to share Postman with the client for integration purposes. Initially, the integration team had to import the OpenAPI JSON and publish the contract to access the APIs. Managing this setup became challenging at times, especially when there were updates to the documentation. This was because the integration team had to make manual edits to the contract, and since the API documentation could only be edited via Postman, it was challenging to keep track of who made the changes.

More Details

Good API documentation is essential for several reasons:

Clarity and Understanding: Documentation provides a clear and concise explanation of how an API works. It helps developers understand the API’s endpoints, request parameters, response formats, and any authentication requirements.

Ease of Integration: Well-documented APIs are easier for developers to integrate into their applications. Clear documentation reduces the learning curve and minimizes errors during implementation.

Collaboration: API documentation serves as a communication medium between API providers and consumers. It facilitates collaboration by ensuring that both parties have a shared understanding of the API’s functionality and usage.

Onboarding: Documentation plays a crucial role in onboarding new developers to an API. It provides a structured guide for developers to get started quickly, saving time and resources.

Troubleshooting: When issues arise, good documentation can help troubleshoot problems more efficiently. Developers can refer to the documentation to verify the correct usage of the API and identify potential issues.

API Versioning: Documentation often includes information about API versioning, which is crucial for maintaining backward compatibility as the API evolves.

Compliance and Security: Documentation can outline security best practices, compliance requirements, and data usage policies, ensuring that developers adhere to necessary standards.

Conclusion

In conclusion, generating Swagger documentation from OpenAPI specifications in a Java Spring Boot project is a powerful way to improve your API documentation and streamline the development process. It promotes collaboration, helps developers understand and use your APIs more effectively, and ultimately leads to better software products.Our company is adopting Swagger over OpenAPI keeping all the crucial benefits of OpenAPI intact.

References

https://swagger.io/docs/
https://docs.spring.io/spring-framework/reference/index.html