/* * File: src/main/java/purchase/document/PurchaseSwagger.java * Description: This class contains static constants that define the summaries, * descriptions, and example responses for the Purchase API documentation. * These constants are utilized for generating Swagger/OpenAPI documentation, * assisting developers and users in understanding the functionality of the * Purchase API endpoints. The constants include: * * - **CREATE_PURCHASE_SUMMARY** and **CREATE_PURCHASE_DESCRIPTION**: * Provide a summary and description for creating a new purchase, detailing * the required fields such as supplier ID, date, status, remarks, and * related purchase items. * * - **GET_PURCHASE_BY_ID_SUMMARY** and **GET_PURCHASE_BY_ID_DESCRIPTION**: * Outline the purpose of retrieving a purchase by its unique ID. * * - **GET_ALL_PURCHASES_SUMMARY** and **GET_ALL_PURCHASES_DESCRIPTION**: * Describe the endpoint for fetching all purchases, including pagination support. * * - **UPDATE_PURCHASE_SUMMARY** and **UPDATE_PURCHASE_DESCRIPTION**: * Provide information on updating the details of an existing purchase using its ID. * * - **DELETE_PURCHASE_SUMMARY** and **DELETE_PURCHASE_DESCRIPTION**: * Explain the process of deleting a purchase by its ID. * * - **SUCCESS_RESPONSE_EXAMPLE**: Contains a JSON example of a successful response * when creating a purchase, 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 purchase with the * specified ID does not exist. * * This class serves as a centralized reference for the Purchase 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 PurchaseSwagger { // Summaries and Descriptions public static final String CREATE_PURCHASE_SUMMARY = "Create a new purchase"; public static final String CREATE_PURCHASE_DESCRIPTION = "Creates a new purchase record including supplier ID, date, status, remarks, and related purchase items."; public static final String GET_PURCHASE_BY_ID_SUMMARY = "Retrieve purchase by ID"; public static final String GET_PURCHASE_BY_ID_DESCRIPTION = "Fetches the details of a purchase by its unique ID."; public static final String GET_ALL_PURCHASES_SUMMARY = "Retrieve all purchases"; public static final String GET_ALL_PURCHASES_DESCRIPTION = "Retrieves all purchase records with pagination support."; public static final String UPDATE_PURCHASE_SUMMARY = "Update purchase by ID"; public static final String UPDATE_PURCHASE_DESCRIPTION = "Updates the details of a purchase record by its unique ID."; public static final String DELETE_PURCHASE_SUMMARY = "Delete purchase by ID"; public static final String DELETE_PURCHASE_DESCRIPTION = "Deletes a purchase record by its unique ID."; public static final String EXPORT_PURCHASE_BY_ID_SUMMARY = "Export purchase order by ID"; public static final String EXPORT_PURCHASE_BY_ID_DESCRIPTION = "Export details of a specific purchase order by its unique ID."; // Example Requests and Responses public static final String CREATE_PURCHASE_REQUEST_EXAMPLE = """ { "supplier_id": 1, "date": "2024-08-31T10:00:00", "status": "pending", "remarks": "N/A", "purchase_items": [ { "product_id": 1, "quantity": 100 } ] } """; public static final String UPDATE_PURCHASE_REQUEST_EXAMPLE = """ { "supplier_id": 1, "date": "2024-08-31T10:00:00", "status": "pending", "remarks": "N/A", "created_by": "admin", "tenant": "Tenant_01", "purchase_items": [ { "product_id": 1, "quantity": 11, "created_by": "admin", "tenant": "Tenant_01" }, { "product_id": 2, "quantity": 10, "created_by": "admin", "tenant": "Tenant_01" } ] } """; public static final String CREATE_PURCHASE_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 201, "details": "Purchase created successfully", "timestamp": "2025-01-28T14:41:10.5777658" }, "data": { "id": 70, "date": "2024-08-31T10:00:00", "status": "pending", "remarks": "N/A", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "purchase_items": [ { "id": 84, "product_id": 1, "quantity": 100, "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:41:10.53116", "updated_at": "2025-01-28T14:41:10.53116", "deleted_at": null } ], "created_at": "2025-01-28T14:41:10.53116", "updated_at": "2025-01-28T14:41:10.53116", "deleted_at": null } } """; public static final String GET_PURCHASE_BY_ID_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "Purchase retrieved successfully", "timestamp": "2025-01-28T14:45:22.0660442" }, "data": { "id": 54, "supplier_id": 14, "supplier_name": "MediSupply Co.", "date": "2025-01-18T18:30:00", "status": "pending", "remarks": "", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-17T09:04:13.399337", "updated_at": "2025-01-17T09:04:13.399337", "purchase_items": [ { "id": 67, "product_id": 17, "product_name": "Creatine", "brand_id": 55, "brand_name": "ON ", "category_id": 31, "category_name": "Tablet", "tax_id": 13, "tax_type": "GST", "tax_rate": 18.0, "quantity": 100, "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-17T09:04:13.399337", "updated_at": "2025-01-17T09:04:13.399337" } ], "columns": { "id": "ID", "product_id": "PRODUCT ID", "product_name": "PRODUCT NAME", "brand_id": "BRAND ID", "brand_name": "BRAND NAME", "category_id": "CATEGORY ID", "category_name": "CATEGORY NAME", "quantity": "QUANTITY", "created_by": "CREATED BY", "tenant": "TENANT", "created_at": "CREATED AT", "updated_at": "UPDATED AT" } } } """; public static final String GET_ALL_PURCHASES_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "Purchases retrieved successfully", "timestamp": "2025-01-28T14:43:23.4328099" }, "data": { "pagination": { "current_page": 1, "per_page": 10, "total": 6, "last_page": 1, "next_page_url": null, "prev_page_url": null }, "items": [ { "id": 54, "supplier_id": 14, "supplier_name": "MediSupply Co.", "date": "2025-01-18T18:30:00", "status": "pending", "remarks": "", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-17T09:04:13.399337", "updated_at": "2025-01-17T09:04:13.399337" } ], "columns": { "id": "ID", "supplier_id": "SUPPLIER ID", "supplier_name": "SUPPLIER NAME", "date": "DATE", "status": "STATUS", "remarks": "REMARKS", "created_by": "CREATED BY", "tenant": "TENANT", "created_at": "CREATED AT", "updated_at": "UPDATED AT" } } } """; public static final String UPDATE_PURCHASE_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "Purchase updated successfully", "timestamp": "2025-01-28T14:45:57.8941162" }, "data": { "id": 54, "date": "2024-08-31T10:00:00", "status": "pending", "remarks": "N/A", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "purchase_items": [ { "id": 85, "product_id": 1, "quantity": 11, "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:45:57.8631058", "updated_at": "2025-01-28T14:45:57.8631058", "deleted_at": null }, { "id": 86, "product_id": 2, "quantity": 10, "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T14:45:57.8631058", "updated_at": "2025-01-28T14:45:57.8631058", "deleted_at": null } ], "created_at": "2025-01-17T09:04:13.399337", "updated_at": "2025-01-28T14:45:57.8631058", "deleted_at": null } } """; public static final String DELETE_PURCHASE_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "message": "Purchase order deleted successfully" } } """; public static final String INTERNAL_SERVER_ERROR_RESPONSE = """ { "status": "error", "meta": { "code": 500, "message": "Internal Server Error" } } """; public static final String EXPORT_PURCHASE_BY_ID_EXAMPLE=""" { "status": "success", "meta": { "code": 200, "details": "Purchase order exported successfully", "timestamp": "2025-01-28T09:30:25.685057" }, "data": { "id": 54, "supplier_id": 14, "supplier_name": "MediSupply Co.", "date": "2025-01-18T18:30:00", "status": "pending", "remarks": "", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-17T09:04:13.399337", "updated_at": "2025-01-17T09:04:13.399337", "purchase_items": [ { "id": 67, "product_id": 17, "product_name": "Creatine", "brand_id": 55, "brand_name": "ON ", "category_id": 31, "category_name": "Tablet", "tax_id": 13, "tax_type": "GST", "tax_rate": 18.0, "quantity": 100, "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-17T09:04:13.399337", "updated_at": "2025-01-17T09:04:13.399337" } ], "columns": { "id": "ID", "product_id": "PRODUCT ID", "product_name": "PRODUCT NAME", "brand_id": "BRAND ID", "brand_name": "BRAND NAME", "category_id": "CATEGORY ID", "category_name": "CATEGORY NAME", "quantity": "QUANTITY", "created_by": "CREATED BY", "tenant": "TENANT", "created_at": "CREATED AT", "updated_at": "UPDATED AT" } } } """; // 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_PURCHASE_SUMMARY, description = CREATE_PURCHASE_DESCRIPTION, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody( content = @Content( mediaType = "application/json", schema = @Schema(implementation = com.nebula.erp.purchase.requestmodel.PurchaseRequest.class), examples = @ExampleObject(value = CREATE_PURCHASE_REQUEST_EXAMPLE) ) ), responses = { @ApiResponse( responseCode = "201", description = "Purchase order created successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = CREATE_PURCHASE_RESPONSE_EXAMPLE) ) ) } ) public @interface CreatePurchaseOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = GET_PURCHASE_BY_ID_SUMMARY, description = GET_PURCHASE_BY_ID_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Purchase order retrieved successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = GET_PURCHASE_BY_ID_RESPONSE_EXAMPLE) ) ), @ApiResponse( responseCode = "404", description = "Purchase order not found", content = @Content(mediaType = "application/json") ) } ) public @interface GetPurchaseByIdOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = GET_ALL_PURCHASES_SUMMARY, description = GET_ALL_PURCHASES_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Purchase orders retrieved successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = GET_ALL_PURCHASES_RESPONSE_EXAMPLE) ) ) } ) public @interface GetAllPurchasesOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = UPDATE_PURCHASE_SUMMARY, description = UPDATE_PURCHASE_DESCRIPTION, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody( content = @Content( mediaType = "application/json", schema = @Schema(implementation = com.nebula.erp.purchase.requestmodel.PurchaseRequest.class), examples = @ExampleObject(value = UPDATE_PURCHASE_REQUEST_EXAMPLE) ) ), responses = { @ApiResponse( responseCode = "200", description = "Purchase order updated successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = UPDATE_PURCHASE_RESPONSE_EXAMPLE) ) ) } ) public @interface UpdatePurchaseOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = DELETE_PURCHASE_SUMMARY, description = DELETE_PURCHASE_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Purchase order deleted successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = DELETE_PURCHASE_RESPONSE_EXAMPLE) ) ), @ApiResponse( responseCode = "404", description = "Purchase order not found", content = @Content(mediaType = "application/json") ) } ) public @interface DeletePurchaseOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = EXPORT_PURCHASE_BY_ID_SUMMARY, description = EXPORT_PURCHASE_BY_ID_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "Purchase order exported successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = EXPORT_PURCHASE_BY_ID_EXAMPLE) ) ) } ) public @interface ExportPurchaseByIdOperation {} }