/* * File: src/main/java/purchase/document/GRNSwagger.java * Description: This class contains static constants that define the summaries, * descriptions, and example responses for the GRN (Goods Receipt Note) API * documentation. These constants are used for generating Swagger/OpenAPI * documentation, making it easier for developers and users to understand * the functionality of the GRN API endpoints. The constants include: * * - **CREATE_GRN_SUMMARY** and **CREATE_GRN_DESCRIPTION**: Provide a summary * and description for creating a new GRN, detailing the required fields * such as purchase order ID, supplier ID, invoice number, and associated * GRN items. * * - **GET_GRN_BY_ID_SUMMARY** and **GET_GRN_BY_ID_DESCRIPTION**: Outline the * purpose of retrieving a GRN by its unique ID. * * - **GET_ALL_GRNS_SUMMARY** and **GET_ALL_GRNS_DESCRIPTION**: Describe the * endpoint for fetching all GRNs, including pagination support. * * - **UPDATE_GRN_SUMMARY** and **UPDATE_GRN_DESCRIPTION**: Provide information * on updating the details of an existing GRN using its ID. * * - **DELETE_GRN_SUMMARY** and **DELETE_GRN_DESCRIPTION**: Explain the process * of deleting a GRN by its ID. * * - **SUCCESS_RESPONSE_EXAMPLE**: Contains a JSON example of a successful * response when creating a GRN, 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 GRN with * the specified ID does not exist. * * This class serves as a centralized reference for the GRN 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 GRNSwagger { // Summaries and Descriptions public static final String CREATE_GRN_SUMMARY = "Create a new GRN (Goods Received Note)"; public static final String CREATE_GRN_DESCRIPTION = "Create a new GRN including items received, quantities, and supplier information."; public static final String GET_GRN_BY_ID_SUMMARY = "Retrieve GRN by ID"; public static final String GET_GRN_BY_ID_DESCRIPTION = "Retrieve a specific GRN by its unique ID."; public static final String GET_ALL_GRNS_SUMMARY = "Retrieve all GRNs"; public static final String GET_ALL_GRNS_DESCRIPTION = "Retrieve a paginated list of all GRNs with optional filters."; // Example Requests public static final String CREATE_GRN_REQUEST_EXAMPLE = """ { "purchase_order_id":61, "supplier_id": 1, "date": "2024-08-31T10:00:00", "invoice_number": "CBS-123456", "grn_items": [ { "product_id": 20, "quantity": 10, "unit_price": 10, "expiration_date": "2024-08-31T10:00:00", "manufacture_date":"2024-08-31T10:00:00", "batch_code":"1235", "tax_id": 5 } ] } """; // Example Responses public static final String CREATE_GRN_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 201, "details": "GRN created successfully", "timestamp": "2025-01-28T15:06:08.7164862" }, "data": { "id": 82, "date": "2025-01-27T18:30:00", "invoice_number": "BK0006776", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "grn_items": [ { "id": 78, "product_id": 17, "quantity": 11, "unit_price": 20.0, "total_price": 259.6, "expiration_date": "2025-04-27", "manufacture_date": "2025-01-27", "batch_code": "test", "tax_id": "18", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T15:06:08.293039", "updated_at": "2025-01-28T15:06:08.293039", "deleted_at": null } ], "created_at": "2025-01-28T15:06:08.1682923", "updated_at": "2025-01-28T15:06:08.1682923", "deleted_at": null, "purchase": { "id": 67, "date": "2025-01-19T13:00:00", "status": "pending", "remarks": "test", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "purchase_items": [ { "id": 83, "product_id": 17, "quantity": 11, "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "tenant": "Arise_Tenant", "created_at": "2025-01-28T11:41:57.039709", "updated_at": "2025-01-28T11:41:57.039709", "deleted_at": null } ], "created_at": "2025-01-20T22:39:49.368066", "updated_at": "2025-01-28T11:41:57.039709", "deleted_at": null } } } """; public static final String GET_GRN_BY_ID_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "GRN retrieved successfully", "timestamp": "2025-01-28T15:14:18.940803" }, "data": { "id": 62, "purchase_order_id": 54, "purchase_date": "2024-08-31T10:00:00", "purchase_status": "pending", "purchase_remarks": "N/A", "purchase_created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "purchase_created_at": "2025-01-17T09:04:13.399337", "purchase_updated_at": "2025-01-28T14:45:57.863106", "supplier_id": 14, "supplier_name": "MediSupply Co.", "date": "2025-01-19T18:30:00", "invoice_number": "BK0006711", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "created_at": "2025-01-17T09:06:16.137555", "grn_items": [ { "id": 62, "product_id": 17, "product_name": "Creatine", "brand_id": 55, "brand_name": "ON ", "category_id": 31, "category_name": "Tablet", "unit_price": 6.0, "tax_id": "18", "tax_rate": 18.0, "quantity": 100, "total_price": 708.0, "manufacture_date": "2025-01-12", "expiration_date": "2025-04-28", "batch_code": "123" } ], "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", "tax_rate": "TAX RATE", "quantity": "QUANTITY", "unit_price": "UNIT PRICE", "total_price": "TOTAL PRICE", "manufacture_date": "MANUFACTURE DATE", "expiration_date": "EXPIRATION DATE", "batch_code": "BATCH CODE", "tax_id": "TAX ID" } } } """; public static final String GET_ALL_GRNS_RESPONSE_EXAMPLE = """ { "status": "success", "meta": { "code": 200, "details": "GRN retrieved successfully", "timestamp": "2025-01-28T14:51:23.1501817" }, "data": { "pagination": { "current_page": 1, "per_page": 10, "total": 4, "last_page": 1, "next_page_url": null, "prev_page_url": null }, "items": [ { "id": 62, "purchase_order_id": 54, "purchase_date": "2024-08-31T10:00:00", "purchase_status": "pending", "purchase_remarks": "N/A", "purchase_created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "purchase_created_at": "2025-01-17T09:04:13.399337", "purchase_updated_at": "2025-01-28T14:45:57.863106", "supplier_id": 14, "supplier_name": "MediSupply Co.", "date": "2025-01-19T18:30:00", "invoice_number": "BK0006711", "created_by": "0d5d2ca9-87ac-4a06-afde-d6f665a23be8", "created_at": "2025-01-17T09:06:16.137555", "grn_items": [ { "id": 62, "product_id": 17, "product_name": "Creatine", "brand_id": 55, "brand_name": "ON ", "category_id": 31, "category_name": "Tablet", "unit_price": 6.0, "tax_id": "18", "tax_rate": 18.0, "quantity": 100, "total_price": 708.0, "manufacture_date": "2025-01-12", "expiration_date": "2025-04-28", "batch_code": "123" } ] } ], "columns": { "id": "ID", "purchase_order_id": "PURCHASE ORDER ID", "supplier_id": "SUPPLIER ID", "supplier_name": "SUPPLIER NAME", "date": "DATE", "invoice_number": "INVOICE NUMBER", "product_id": "PRODUCT ID", "quantity": "QUANTITY", "unit_price": "UNIT PRICE", "total_price": "TOTAL PRICE", "expiration_date": "EXPIRATION DATE", "tax_id": "TAX ID", "created_by": "CREATED BY", "created_at": "CREATED AT" } } } """; 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_GRN_SUMMARY, description = CREATE_GRN_DESCRIPTION, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody( content = @Content( mediaType = "application/json", schema = @Schema(implementation = com.nebula.erp.purchase.requestmodel.GRNRequest.class), examples = @ExampleObject(value = CREATE_GRN_REQUEST_EXAMPLE) ) ), responses = { @ApiResponse( responseCode = "201", description = "GRN created successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = CREATE_GRN_RESPONSE_EXAMPLE) ) ) } ) public @interface CreateGRNOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = GET_GRN_BY_ID_SUMMARY, description = GET_GRN_BY_ID_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "GRN retrieved successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = GET_GRN_BY_ID_RESPONSE_EXAMPLE) ) ) } ) public @interface GetGRNByIdOperation {} @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Operation( summary = GET_ALL_GRNS_SUMMARY, description = GET_ALL_GRNS_DESCRIPTION, responses = { @ApiResponse( responseCode = "200", description = "GRNs retrieved successfully", content = @Content( mediaType = "application/json", examples = @ExampleObject(value = GET_ALL_GRNS_RESPONSE_EXAMPLE) ) ) } ) public @interface GetAllGRNsOperation {} }