ApiInfo Class Documentation

The ApiInfo class encapsulates general metadata about an API, providing a structured way to define essential information such as the API's title, version, description, terms of service, contact details, and licensing information. This metadata is critical for generating clear, professional API documentation and is designed to integrate seamlessly with JSON serialization frameworks.

---

Overview

The ApiInfo class provides:

• A fluent API interface for convenient and readable configuration.
• Support for JSON serialization using Jackson annotations.
• Flexible storage for contact and license information through key-value maps.
• Methods to add detailed contact and licensing entries dynamically.

---

Class Details

Package

package documentation;

Imports

• Jackson annotations for JSON serialization (JsonInclude, JsonProperty)
• Lombok’s @Getter to generate getter methods automatically
• Standard Java utility classes (HashMap, Map)

---

Fields

Field	Type	Description
title	String	The API’s title or name.
apiVersion	String	The version identifier for the API.
description	String	A short summary describing the API’s purpose.
termsOfService	String	Terms of service URL or description.
contact	Map<String, Object>	Key-value pairs for contact information (email, phone, etc.).
license	Map<String, Object>	Key-value pairs for license information (name, URL, etc.).

---

Constructors

• Default constructor — Creates a new, empty ApiInfo instance.
• Static factory method getInstance() — Returns a new ApiInfo instance, promoting a standardized way to create objects.

---

Methods

Fluent Setters

Each setter returns the current ApiInfo instance to enable method chaining:

• setTitle(String title) — Sets the API’s title.
• setApiVersion(String apiVersion) — Sets the API version.
• setDescription(String description) — Sets the API description.
• setTermsOfService(String termsOfService) — Sets terms of service information.
• setContact(Map<String, Object> contact) — Sets the entire contact map.
• setLicense(Map<String, Object> license) — Sets the entire license map.

Adders for Maps

• addContact(String key, Object value) — Adds a contact key-value pair; initializes the map if null.
• addLicense(String key, Object value) — Adds a license key-value pair; initializes the map if null.

Other

• toString() — Returns a string representation of the ApiInfo object with all fields.

---

JSON Serialization Behavior

• The class is annotated with Jackson’s @JsonInclude(JsonInclude.Include.NON_NULL) to exclude null fields from JSON output.
• The apiVersion field is serialized with the JSON key "version" due to the @JsonProperty("version") annotation.
• The contact and license maps exclude empty or null content during serialization.

---

Example Usage

ApiInfo apiInfo = ApiInfo.getInstance()
    .setTitle("My Awesome API")
    .setApiVersion("1.0")
    .setDescription("This API provides awesome features.")
    .setTermsOfService("https://example.com/terms")
    .addContact("email", "support@example.com")
    .addContact("phone", "+123456789")
    .addLicense("name", "Apache 2.0")
    .addLicense("url", "https://www.apache.org/licenses/LICENSE-2.0");