Skip to content

Commit

Permalink
MOSIP-38883 :Improve API documentation in swagger and deprecate endpo…
Browse files Browse the repository at this point in the history 
…ints (#1082)

Signed-off-by: sudeep <[email protected]>
  • Loading branch information
@Sudeep7353
Sudeep7353 authored Jan 10, 2025
1 parent 9d5a043 commit 2a70f9b
Show file tree
Hide file tree
Showing 5 changed files with 209 additions and 102 deletions.
73 changes: 43 additions & 30 deletions ...nagement-service/src/main/java/io/mosip/pms/device/controller/DeviceDetailController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,19 +78,18 @@ public class DeviceDetailController {

@Autowired
RequestValidator requestValidator;

/**
* Post API to insert a new row of DeviceDetail data
*
* @param deviceDetailRequestDto input parameter deviceRequestDto
*
* @return ResponseEntity DeviceDetail which is inserted successfully
* {@link ResponseEntity}

/*
* This API has been deprecated since the release-1.3.0
* It has been replaced by the new POST /securebiometricinterface/{sbiId}/devices endpoint.
* The functionality provided by this API is now available in the new endpoint.
* Please use the new endpoint for all future requests.
*/
@Deprecated(since = "release-1.3.0")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPostdevicedetail())")
@ResponseFilter
@PostMapping
@Operation(summary = "Service to save DeviceDetail", description = "Saves DeviceDetail and return DeviceDetail id")
@Operation(summary = "Service to save DeviceDetail - deprecated since release-1.3.0.", description = "This API has been deprecated since the 1.3.0 release and replaced by the POST /securebiometricinterface/{sbiId}/devices endpoint.")
@ApiResponses({ @ApiResponse(code = 201, message = "When DeviceDetail successfully created"),
@ApiResponse(code = 400, message = "When Request body passed is null or invalid"),
@ApiResponse(code = 500, message = "While creating DeviceDetail any error occured") })
Expand All @@ -113,19 +112,14 @@ public ResponseWrapper<IdDto> createDeviceDetail(

}

/**
* Put API to update a row of DeviceDetail data
*
* @param deviceDetailRequestDto input parameter deviceRequestDto
*
* @return ResponseEntity DeviceDetail which is updated successfully
* {@link ResponseEntity}
/*
* This API has been deprecated since the release-1.3.0
*/
@Deprecated
@Deprecated(since = "release-1.3.0")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPutdevicedetail())")
@ResponseFilter
@PutMapping
@Operation(summary = "Service to update DeviceDetails", description = "This API has been deprecated since 1.3.x release.")
@Operation(summary = "Service to update DeviceDetails - deprecated since release-1.3.0.", description = "This API has been deprecated since release-1.3.0.")
@ApiResponses({ @ApiResponse(code = 201, message = "When DeviceDetail successfully updated"),
@ApiResponse(code = 400, message = "When Request body passed is null or invalid"),
@ApiResponse(code = 500, message = "While updating DeviceDetail any error occured") })
Expand All @@ -146,16 +140,19 @@ public ResponseWrapper<IdDto> updateDeviceDetail(
"AUT-007", deviceDetailRequestDto.getRequest().getId(), "deviceDetailId");
return responseWrapper;
}

/**
*
* @param deviceDetailRequestDto
* @return

/*
* This API has been deprecated since the release-1.3.0
* It has been replaced by the new PATCH devicedetail/{id}/approval endpoint.
* The functionality provided by this API is now available in the new endpoint.
* Please use the new endpoint for all future requests.
*/
@Deprecated(since = "release-1.3.0")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPatchdevicedetail())")
@ResponseFilter
@PatchMapping
@Operation(summary = "Service to approve/reject DeviceDetail", description = "Approve DeviceDetail and returns success message")
@Operation(summary = "Service to approve/reject DeviceDetail - deprecated since 1.3.0 release.",
description = "This API has been deprecated since the 1.3.0 release and replaced by the PATCH devicedetail/{id}/approval endpoint.")
@ApiResponses({ @ApiResponse(code = 201, message = "When DeviceDetail successfully approved/rejected"),
@ApiResponse(code = 400, message = "When Request body passed is null or invalid"),
@ApiResponse(code = 500, message = "While approving/rejecting DeviceDetail any error occured") })
Expand All @@ -177,11 +174,19 @@ public ResponseWrapper<String> approveDeviceDetails(

return responseWrapper;
}


/*
* This API has been deprecated since the release-1.3.0
* It has been replaced by the new GET /devicedetail/search/v2 endpoint.
* The functionality provided by this API is now available in the new endpoint.
* Please use the new endpoint for all future requests.
*/
@Deprecated(since = "release-1.3.0")
@ResponseFilter
@PostMapping("/search")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPostdevicedetailsearch())")
@Operation(summary = "Service to search DeviceDetails", description = "ervice to search DeviceDetails")
@Operation(summary = "Service to search DeviceDetails - deprecated since 1.3.0 release.",
description = "This API has been deprecated since the 1.3.0 release and replaced by the GET /devicedetail/search/v2 endpoint.")
public ResponseWrapper<PageResponseDto<DeviceDetailSearchResponseDto>> searchDeviceDetails(
@RequestBody @Valid RequestWrapper<DeviceSearchDto> request) {
ResponseWrapper<PageResponseDto<DeviceDetailSearchResponseDto>> responseWrapper = new ResponseWrapper<>();
Expand All @@ -199,11 +204,19 @@ public ResponseWrapper<PageResponseDto<RegistrationSubTypeDto>> searchDeviceType
responseWrapper.setResponse(deviceDetaillService.searchDeviceType(RegistrationDeviceSubType.class, request.getRequest()));
return responseWrapper;
}


/*
* This API has been deprecated since the release-1.3.0
* It has been replaced by the new GET /devicedetail/search/v2 endpoint.
* The functionality provided by this API is now available in the new endpoint.
* Please use the new endpoint for all future requests.
*/
@Deprecated(since = "release-1.3.0")
@ResponseFilter
@PostMapping("/filtervalues")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPostdevicedetailfiltervalues())")
@Operation(summary = "Service to filter DeviceDetails", description = "Service to filter DeviceDetails")
@Operation(summary = "Service to filter DeviceDetails - deprecated since 1.3.0 release.",
description = "This API has been deprecated since the 1.3.0 release and replaced by the GET /devicedetail/search/v2 endpoint.")
public ResponseWrapper<FilterResponseCodeDto> filterValues(
@RequestBody @Valid RequestWrapper<DeviceFilterValueDto> request) {
ResponseWrapper<FilterResponseCodeDto> responseWrapper = new ResponseWrapper<>();
Expand Down Expand Up @@ -254,7 +267,7 @@ public ResponseWrapperV2<DeviceDetailResponseDto> deactivateDevice(@PathVariable

@PreAuthorize("hasAnyRole(@authorizedRoles.getPostdevicewithsbimapping())")
@PostMapping(value = "/{id}/approval")
@Operation(summary = "Added in release-1.3.0, This endpoint allows Partner Admin users to approve or reject devices and activate the mapping between a device and an SBI",
@Operation(summary = "Added in release-1.3.0, available for Partner Admin, allows user to approve or reject devices and activate the mapping between a device and an SBI",
description = "This endpoint allows Partner Admin users to approve or reject devices and activate the mapping between a device and an SBI. It is exclusively accessible to users with the PARTNER_ADMIN role.")
@io.swagger.v3.oas.annotations.responses.ApiResponses(value = {
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "OK"),
Expand All @@ -271,7 +284,7 @@ public ResponseWrapperV2<Boolean> approveOrRejectMappingDeviceToSbi(@PathVariabl

@PreAuthorize("hasAnyRole(@authorizedRoles.getGetalldevicedetails())")
@GetMapping(value = "/search/v2")
@Operation(summary = "Added in release-1.3.0, This endpoint fetches the list of all devices created by all partners", description = "This endpoint fetches the list of all devices created by all partners. It enhances the earlier /partners/devicedetail/search endpoint by improving performance, handling deactivated statuses, and adding SBI ID and version details. The API supports pagination, sorting and filtering and is designed exclusively for Partner Admin users.")
@Operation(summary = "Added in release-1.3.0, available only for Partner Admin, retrieves a list of all devices created by all partners", description = "This endpoint fetches the list of all devices created by all partners. It enhances the earlier /partners/devicedetail/search endpoint by improving performance, handling deactivated statuses, and adding SBI ID and version details. The API supports pagination, sorting and filtering and is designed exclusively for Partner Admin users.")
@io.swagger.v3.oas.annotations.responses.ApiResponses(value = {
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "OK"),
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Unauthorized", content = @Content(schema = @Schema(hidden = true))),
Expand Down
28 changes: 16 additions & 12 deletions ...agement-service/src/main/java/io/mosip/pms/device/controller/FTPChipDetailController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,19 +110,14 @@ public ResponseWrapper<IdDto> createDeviceDetail(

}

/**
* Put API to update a row of DeviceDetail data
*
* @param deviceDetailRequestDto input parameter deviceRequestDto
*
* @return ResponseEntity DeviceDetail which is updated successfully
* {@link ResponseEntity}
/*
* This API has been deprecated since the release-1.3.0
*/
@Deprecated
@Deprecated(since = "release-1.3.0")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPutftpchipdetail())")
@ResponseFilter
@PutMapping
@Operation(summary = "Service to update ftp chip detail", description = "This API has been deprecated since 1.3.x release.")
@Operation(summary = "Service to update ftp chip detail - deprecated since 1.3.0 release.", description = "This API has been deprecated since 1.3.0 release.")
@ApiResponses({ @ApiResponse(code = 201, message = "When ftp chip detail successfully updated"),
@ApiResponse(code = 400, message = "When Request body passed is null or invalid"),
@ApiResponse(code = 500, message = "While updating ftp chip detail any error occured") })
Expand Down Expand Up @@ -239,11 +234,19 @@ public ResponseWrapper<FtpCertDownloadResponeDto> getPartnerCertificate(
"AUT-007", ftpChipDetailId, "ftpChipDetailId");
return response;
}


/*
* This API has been deprecated since the release-1.3.0
* It has been replaced by the new GET /ftpchipdetail/search/v2 endpoint.
* The functionality provided by this API is now available in the new endpoint.
* Please use the new endpoint for all future requests.
*/
@Deprecated(since = "release-1.3.0")
@ResponseFilter
@PostMapping("/search")
@PreAuthorize("hasAnyRole(@authorizedRoles.getPostftpchipdetailsearch())")
@Operation(summary = "Service to serach ftp chip details", description = "Service to serach ftp chip details")
@Operation(summary = "Service to search ftp chip details - deprecated since 1.3.0 release.",
description = "This API has been deprecated since the 1.3.0 release and replaced by the GET /ftpchipdetail/search/v2 endpoint.")
public ResponseWrapper<PageResponseDto<FTPSearchResponseDto>> searchFtpChipDetails(
@RequestBody @Valid RequestWrapper<DeviceSearchDto> request) {
ResponseWrapper<PageResponseDto<FTPSearchResponseDto>> responseWrapper = new ResponseWrapper<>();
Expand Down Expand Up @@ -282,7 +285,8 @@ public ResponseWrapperV2<FtmCertificateDownloadResponseDto> getFtmCertificateDat

@PreAuthorize("hasAnyRole(@authorizedRoles.getGetpartnersftmchipdetails())")
@GetMapping(value = "/search/v2")
@Operation(summary = "Added in release-1.3.0, This endpoint retrieves the list of all FTM chip details created by all partners", description = "This endpoint, available for Partner Admin users only, retrieves the list of all FTM chip details created by all partners. It upgrades the earlier GET endpoint /ftpchipdetail/search by adding performance improvements and support for deactivated status. Additionally, it supports pagination, sorting, and filtering. This endpoint is configured for the role: PARTNER_ADMIN")
@Operation(summary = "Added in release-1.3.0, available only for Partner Admin users, retrieves a list of all FTM chip details created by all partners",
description = "This endpoint, available for Partner Admin users only, retrieves the list of all FTM chip details created by all partners. It upgrades the earlier GET endpoint /ftpchipdetail/search by adding performance improvements and support for deactivated status. Additionally, it supports pagination, sorting, and filtering. This endpoint is configured for the role: PARTNER_ADMIN")
@io.swagger.v3.oas.annotations.responses.ApiResponses(value = {
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "OK"),
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Unauthorized", content = @Content(schema = @Schema(hidden = true))),
Expand Down
Loading

0 comments on commit 2a70f9b

Please sign in to comment.