/* * File: src/main/java/purchase/document/SupplierSwagger.java * Description: This class contains static constants that define the summaries, * descriptions, and example responses for the Supplier API documentation. * These constants are utilized for generating Swagger/OpenAPI documentation, * assisting developers and users in understanding the functionality of the * Supplier API endpoints. The constants include: * * - **CREATE_SUPPLIER_SUMMARY** and **CREATE_SUPPLIER_DESCRIPTION**: * Provide a summary and description for creating a new supplier, detailing * the required fields such as supplier ID, supplier name, contact information, * and address. * * - **GET_SUPPLIER_BY_ID_SUMMARY** and **GET_SUPPLIER_BY_ID_DESCRIPTION**: * Outline the purpose of retrieving a supplier by its unique ID. * * - **GET_ALL_SUPPLIERS_SUMMARY** and **GET_ALL_SUPPLIERS_DESCRIPTION**: * Describe the endpoint for fetching all suppliers, including pagination support. * * - **UPDATE_SUPPLIER_SUMMARY** and **UPDATE_SUPPLIER_DESCRIPTION**: * Provide information on updating the details of an existing supplier using its ID. * * - **DELETE_SUPPLIER_SUMMARY** and **DELETE_SUPPLIER_DESCRIPTION**: * Explain the process of deleting a supplier by its ID. * * - **SUCCESS_RESPONSE_EXAMPLE**: Contains a JSON example of a successful response * when creating a supplier, demonstrating the structure and expected fields * of the response data. * * - **NOT_FOUND_RESPONSE_EXAMPLE**: Includes a JSON example for a not found response, * specifying the error status, code, and details when a supplier with the * specified ID does not exist. * * This class serves as a centralized reference for the Supplier API's documentation, * promoting consistency and clarity in API usage and integration. */ package com.nebula.erp.purchase.document; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; public class SupplierSwagger { // Summaries and Descriptions public static final String CREATE_SUPPLIER_SUMMARY = "Create a new supplier"; public static final String CREATE_SUPPLIER_DESCRIPTION = "Creates a new supplier record including supplier ID, supplier name, contact, address and related supplier details."; public static final String GET_SUPPLIER_BY_ID_SUMMARY = "Retrieve supplier by ID"; public static final String GET_SUPPLIER_BY_ID_DESCRIPTION = "Fetches the details of a supplier by its unique ID."; public static final String GET_ALL_SUPPLIERS_SUMMARY = "Retrieve all suppliers"; public static final String GET_ALL_SUPPLIERS_DESCRIPTION = "Retrieves all supplier records with pagination support."; public static final String UPDATE_SUPPLIER_SUMMARY = "Update supplier by ID"; public static final String UPDATE_SUPPLIER_DESCRIPTION = "Updates the details of a supplier record by its unique ID."; public static final String DELETE_SUPPLIER_SUMMARY = "Delete supplier by ID"; public static final String DELETE_SUPPLIER_DESCRIPTION = "Deletes a supplier record by its unique ID."; // Example Requests public static final String CREATE_SUPPLIER_REQUEST_EXAMPLE = """ { "supplier_id": "SUP-6789", "supplier_name": "J&J Supplies", "contact_person": "John Doe", "phone_number": "+1-800-123-4567", "email_address": "john.doe@acmesupplies.com", "address": "123 Elm Street", "city": "Metropolis", "state_province": "New York", "zip_postal_code": "10001", "country": "USA", "website": "https://www.acmesupplies.com", "supplier_type": "Distributor", "notes": "Preferred supplier for office supplies" } """; public static final String UPDATE_SUPPLIER_REQUEST_EXAMPLE = """ { "supplier_id": "SUP-12345", "supplier_name": "Acme Supplies", "contact_person": "John Doe", "phone_number": "+1-800-123-4567", "email_address": "john.doe@acmesupplies.com", "address": "123 Elm Street", "city": "Metropolis", "state_province": "New York", "zip_postal_code": "10001", "country": "USA", "website": "https://www.acmesupplies.com", "supplier_type": "Distributor", "notes": "Preferred supplier for office supplies", "created_by": "admin", "tenant": "Tenant_02" } """; // Example Responses public static final String CREATE_SUPPLIER_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 201, "details": "Supplier created successfully", "timestamp": "2025-01-28T14:25:49.7237055" }, "data": { "id": 26, "supplier_id": "SUP-6789", "supplier_name": "J&J Supplies", "contact_person": "John Doe", "phone_number": "+1-800-123-4567", "email_address": "john.doe@acmesupplies.com", "address": "123 Elm Street", "city": "Metropolis", "state_province": "New York", "zip_postal_code": "10001", "country": "USA", "website": "https://www.acmesupplies.com", "supplier_type": "Distributor", "notes": "Preferred supplier for office supplies", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:25:49.6926561", "updated_at": "2025-01-28T14:25:49.6926561", "deleted_at": null } } """; public static final String GET_SUPPLIER_BY_ID_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "Supplier retrieved successfully", "timestamp": "2025-01-28T14:30:55.5232768" }, "data": { "id": 26, "supplier_id": "SUP-6789", "supplier_name": "J&J Supplies", "contact_person": "John Doe", "phone_number": "+1-800-123-4567", "email_address": "john.doe@acmesupplies.com", "address": "123 Elm Street", "city": "Metropolis", "state_province": "New York", "zip_postal_code": "10001", "country": "USA", "website": "https://www.acmesupplies.com", "supplier_type": "Distributor", "notes": "Preferred supplier for office supplies", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:25:49.692656", "updated_at": "2025-01-28T14:25:49.692656", "deleted_at": null } } """; public static final String GET_ALL_SUPPLIERS_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "Suppliers retrieved successfully", "timestamp": "2025-01-28T14:31:15.8419634" }, "data": { "pagination": { "current_page": 1, "per_page": 10, "total": 2, "last_page": 1, "next_page_url": null, "prev_page_url": null }, "items": [ { "id": 26, "supplier_id": "SUP-6789", "supplier_name": "J&J Supplies", "contact_person": "John Doe", "phone_number": "+1-800-123-4567", "email_address": "john.doe@acmesupplies.com", "address": "123 Elm Street", "city": "Metropolis", "state_province": "New York", "zip_postal_code": "10001", "country": "USA", "website": "https://www.acmesupplies.com", "supplier_type": "Distributor", "notes": "Preferred supplier for office supplies", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:25:49.692656", "updated_at": "2025-01-28T14:25:49.692656", "deleted_at": null } ], "columns": { "id": "ID", "supplier_id": "SUPPLIER ID", "supplier_name": "SUPPLIER NAME", "contact_person": "CONTACT PERSON", "phone_number": "PHONE NUMBER", "email_address": "EMAIL ADDRESS", "address": "ADDRESS", "city": "CITY", "state_province": "STATE/PROVINCE", "zip_postal_code": "ZIP/POSTAL CODE", "country": "COUNTRY", "website": "WEBSITE", "supplier_type": "SUPPLIER TYPE", "notes": "NOTES", "created_by": "CREATED BY", "tenant": "TENANT", "created_at": "CREATED AT", "updated_at": "UPDATED AT", "deleted_at": "DELETED AT" } } } """; public static final String UPDATE_SUPLIER_RESPONSE_EXAMPLE= """ { "status": "success", "meta": { "code": 200, "details": "Supplier updated successfully", "timestamp": "2025-01-28T14:34:22.4994933" }, "data": { "id": 26, "supplier_id": "SUP-12345", "supplier_name": "Acme Supplies", "contact_person": "John Doe", "phone_number": "+1-800-123-4567", "email_address": "john.doe@acmesupplies.com", "address": "123 Elm Street", "city": "Metropolis", "state_province": "New York", "zip_postal_code": "10001", "country": "USA", "website": "https://www.acmesupplies.com", "supplier_type": "Distributor", "notes": "Preferred supplier for office supplies", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:25:49.692656", "updated_at": "2025-01-28T14:25:49.692656", "deleted_at": null } } """; public static final String DELETE_SUPPLIER_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "Supplier deleted successfully", "timestamp": "2025-01-28T14:36:24.9817032" }, "data": null } """; public static final String INTERNAL_SERVER_ERROR_RESPONSE = """ { "status": "error", "meta": { "code": 500, "message": "Internal Server Error" } } """; // Global Error Response Annotation @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @ApiResponse( responseCode = "500", description = "Internal Server Error", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = INTERNAL_SERVER_ERROR_RESPONSE) ) ) public @interface GlobalErrorResponse {} // Modular Annotations for Each API @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = CREATE_SUPPLIER_SUMMARY, description = CREATE_SUPPLIER_DESCRIPTION, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody( content = @Content( mediaType = "application/json", schema = @Schema(implementation = com.nebula.erp.purchase.requestmodel.SupplierRequest.class), examples = @ExampleObject(value = CREATE_SUPPLIER_REQUEST_EXAMPLE) ) ), responses = { @ApiResponse( responseCode = "201", description = "Supplier created successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = CREATE_SUPPLIER_RESPONSE_EXAMPLE) ) ) } ) public @interface CreateSupplierOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = GET_SUPPLIER_BY_ID_SUMMARY, description = GET_SUPPLIER_BY_ID_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Supplier retrieved successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = GET_SUPPLIER_BY_ID_RESPONSE_EXAMPLE) ) ), @ApiResponse( responseCode = "404", description = "Supplier not found", content = @Content(mediaType = "application/json") ) } ) public @interface GetSupplierByIdOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = GET_ALL_SUPPLIERS_SUMMARY, description = GET_ALL_SUPPLIERS_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Suppliers retrieved successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = GET_ALL_SUPPLIERS_RESPONSE_EXAMPLE) ) ) } ) public @interface GetAllSuppliersOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = UPDATE_SUPPLIER_SUMMARY, description = UPDATE_SUPPLIER_DESCRIPTION, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody( content = @Content( mediaType = "application/json", schema = @Schema(implementation = com.nebula.erp.purchase.requestmodel.SupplierRequest.class), examples = @ExampleObject(value = UPDATE_SUPPLIER_REQUEST_EXAMPLE) ) ), responses = { @ApiResponse( responseCode = "200", description = "Supplier updated successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = UPDATE_SUPLIER_RESPONSE_EXAMPLE) ) ) } ) public @interface UpdateSupplierOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = DELETE_SUPPLIER_SUMMARY, description = DELETE_SUPPLIER_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Supplier deleted successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = DELETE_SUPPLIER_RESPONSE_EXAMPLE) ) ), @ApiResponse( responseCode = "404", description = "Supplier not found", content = @Content(mediaType = "application/json") ) } ) public @interface DeleteSupplierOperation {} }