KRYSTALM7 opened a new issue, #102: URL: https://github.com/apache/fineract-loan-origination/issues/102
## Description Several REST controllers are missing OpenAPI annotations, resulting in incomplete Swagger UI documentation. SpringDoc OpenAPI is already a dependency in `pom.xml` and the annotation pattern is established in other controllers this issue is purely additive. ## Current Behavior **Documented controllers** (have `@Tag` + `@Operation`): - `Staff` — Authenticated staff information - `Approval Workflow` — Record loan officer / branch manager / credit committee decisions - `Loan Applications` — Create, submit, and review loan applications - `Disbursement` — Bridge an APPROVED application into a disbursed Fineract loan - `Admin — Staff Management` — Create, list, update, and deactivate staff accounts **Undocumented controllers** (raw class names, no descriptions in Swagger UI): - `auth-controller` — 4 POST endpoints with no summaries or descriptions - `customer-loan-application-controller` — 5 endpoints with no descriptions - `admin-customer-controller` — 1 endpoint with no description - `customer-profile-controller` — 1 endpoint with no description - `crypto-key-controller` — 1 endpoint with no description ### Screenshot — Documented controllers (target state) <img width="1915" height="1018" alt="Image" src="https://github.com/user-attachments/assets/296b30c9-f46b-458d-9134-8bcd6e7e8252"; /> ### Screenshot — Undocumented controllers (current state) <img width="1920" height="769" alt="Image" src="https://github.com/user-attachments/assets/9cfc931b-5cb1-4312-acd5-e2aef6848fe9"; /> <img width="1920" height="691" alt="Image" src="https://github.com/user-attachments/assets/a1432a6d-debf-4900-ae9a-fb05b72ed9a8"; /> ## Expected Behavior All REST controllers should have: - `@Tag` at class level with a human-readable `name` and `description` - `@Operation` on every endpoint with a concise `summary` and `description` - `@ApiResponse` annotations for relevant status codes (`200`, `400`, `401`) ## Steps to Reproduce 1. Start the backend (`./mvnw spring-boot:run`) 2. Navigate to `http://localhost:8082/swagger-ui.html` 3. Scroll to `auth-controller`, `customer-loan-application-controller`, `admin-customer-controller`, `customer-profile-controller`, and `crypto-key-controller` 4. Compare against `Loan Applications` or `Admin — Staff Management` — notice the missing titles and endpoint descriptions ## Acceptance Criteria - [ ] `@Tag` and `@Operation` added to `AuthController` (all 4 endpoints: `/auth/login`, `/auth/login/encrypted`, `/auth/staff/login`, `/auth/staff/login/encrypted`) - [ ] `@Tag` and `@Operation` added to `CustomerLoanApplicationController` (all 5 endpoints) - [ ] `@Tag` and `@Operation` added to `AdminCustomerController` - [ ] `@Tag` and `@Operation` added to `CustomerProfileController.me()` - [ ] `@Tag` and `@Operation` added to `CryptoKeyController.getPublicKey()` - [ ] `@ApiResponse` added for `200`, `400`, and `401` where relevant - [ ] Swagger UI shows human-readable group names and descriptions for all controllers after changes - [ ] Annotation style matches existing documented controllers - [ ] No business logic or behavior is changed ## Files to Modify - `src/main/java/org/apache/fineract/los/api/AuthController.java` - `src/main/java/org/apache/fineract/los/api/CustomerLoanApplicationController.java` - `src/main/java/org/apache/fineract/los/api/AdminCustomerController.java` - `src/main/java/org/apache/fineract/los/api/CustomerProfileController.java` - `src/main/java/org/apache/fineract/los/api/CryptoKeyController.java` ## Technical Notes All required annotations are from `io.swagger.v3.oas.annotations` — already on the classpath via SpringDoc. Use `LoanApplicationController` and `AdminStaffController` as style references. Keep descriptions concise and focused on what the endpoint does, not how it is implemented. Run the app and verify `swagger-ui.html` after each controller to confirm the documentation renders correctly. > ⚠️ This issue should only be picked up after #101 is closed and merged. --- **JIRA:** [FINERACT-2442](https://issues.apache.org/jira/browse/FINERACT-2442) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
