From 4e2052b1fd13159b4e5d7e1380a684671092d394 Mon Sep 17 00:00:00 2001 From: maximesson Date: Fri, 5 Jun 2020 09:12:55 +0200 Subject: [PATCH] Add description to parameters in policy controller Change-Id: Ib09bd36c6f0a78ac298671f54071ecededac2191 Issue-ID: NONRTRIC-158 Signed-off-by: maximesson --- policy-agent/docs/api.yaml | 53 +++++++++++++-------- .../policyagent/controllers/PolicyController.java | 54 +++++++++++++++------- 2 files changed, 72 insertions(+), 35 deletions(-) diff --git a/policy-agent/docs/api.yaml b/policy-agent/docs/api.yaml index f3dd06c6..5de8b29f 100644 --- a/policy-agent/docs/api.yaml +++ b/policy-agent/docs/api.yaml @@ -26,19 +26,22 @@ paths: parameters: - name: ric in: query - description: ric + description: The name of the Near-RT RIC to get policies for. required: false type: string + allowEmptyValue: false - name: service in: query - description: service + description: The name of the service to get policies for. required: false type: string + allowEmptyValue: false - name: type in: query - description: type + description: The name of the policy type to get policies for. required: false type: string + allowEmptyValue: false responses: '200': description: Policies @@ -66,9 +69,10 @@ paths: parameters: - name: id in: query - description: id + description: The ID of the policy instance. required: true type: string + allowEmptyValue: false responses: '200': description: Policy found @@ -93,9 +97,10 @@ paths: parameters: - name: id in: query - description: id + description: The ID of the policy instance. required: true type: string + allowEmptyValue: false - in: body name: jsonBody description: jsonBody @@ -104,25 +109,30 @@ paths: type: object - name: ric in: query - description: ric + description: The name of the Near-RT RIC where the policy will be created. required: true type: string + allowEmptyValue: false - name: service in: query - description: service + description: The name of the service creating the policy. required: true type: string + allowEmptyValue: false - name: transient in: query - description: transient + description: If the policy is transient or not (boolean defaulted to false). A policy is transient if it will be forgotten when the service needs to reconnect to the Near-RT RIC. required: false type: boolean default: false + allowEmptyValue: false + x-example: false - name: type in: query - description: type + description: The name of the policy type. required: false type: string + allowEmptyValue: false responses: '200': description: Policy updated @@ -155,9 +165,10 @@ paths: parameters: - name: id in: query - description: id + description: The ID of the policy instance. required: true type: string + allowEmptyValue: false responses: '200': description: OK @@ -191,19 +202,22 @@ paths: parameters: - name: ric in: query - description: ric + description: The name of the Near-RT RIC to get policies for. required: false type: string + allowEmptyValue: false - name: service in: query - description: service + description: The name of the service to get policies for. required: false type: string + allowEmptyValue: false - name: type in: query - description: type + description: The name of the policy type to get policies for. required: false type: string + allowEmptyValue: false responses: '200': description: Policy ids @@ -231,9 +245,10 @@ paths: parameters: - name: id in: query - description: id + description: The ID of the policy type to get the definition for. required: true type: string + allowEmptyValue: false responses: '200': description: Policy schema @@ -259,9 +274,10 @@ paths: parameters: - name: ric in: query - description: ric + description: The name of the Near-RT RIC to get the definitions for. required: false type: string + allowEmptyValue: false responses: '200': description: Policy schemas @@ -289,9 +305,10 @@ paths: parameters: - name: id in: query - description: id + description: The ID of the policy. required: true type: string + allowEmptyValue: false responses: '200': description: Policy status @@ -317,9 +334,10 @@ paths: parameters: - name: ric in: query - description: ric + description: The name of the Near-RT RIC to get types for. required: false type: string + allowEmptyValue: false responses: '200': description: Policy type names @@ -625,4 +643,3 @@ definitions: format: int64 description: time since last invocation by the service title: ServiceStatus - diff --git a/policy-agent/src/main/java/org/oransc/policyagent/controllers/PolicyController.java b/policy-agent/src/main/java/org/oransc/policyagent/controllers/PolicyController.java index 49d77028..017a9fd9 100644 --- a/policy-agent/src/main/java/org/oransc/policyagent/controllers/PolicyController.java +++ b/policy-agent/src/main/java/org/oransc/policyagent/controllers/PolicyController.java @@ -25,6 +25,7 @@ import com.google.gson.GsonBuilder; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; @@ -98,7 +99,8 @@ public class PolicyController { value = { @ApiResponse(code = 200, message = "Policy schemas", response = Object.class, responseContainer = "List"), // @ApiResponse(code = 404, message = "RIC is not found", response = String.class)}) - public ResponseEntity getPolicySchemas(@RequestParam(name = "ric", required = false) String ricName) { + public ResponseEntity getPolicySchemas(@ApiParam(name = "ric", required = false, value = "The name of " +// + "the Near-RT RIC to get the definitions for.")@RequestParam(name = "ric", required = false) String ricName) { if (ricName == null) { Collection types = this.policyTypes.getAll(); return new ResponseEntity<>(toPolicyTypeSchemasJson(types), HttpStatus.OK); @@ -118,7 +120,8 @@ public class PolicyController { value = { // @ApiResponse(code = 200, message = "Policy schema", response = Object.class), @ApiResponse(code = 404, message = "RIC is not found", response = String.class)}) - public ResponseEntity getPolicySchema(@RequestParam(name = "id", required = true) String id) { + public ResponseEntity getPolicySchema(@ApiParam(name = "id", required = true, value = "The ID of the " +// + "policy type to get the definition for.")@RequestParam(name = "id", required = true) String id) { try { PolicyType type = policyTypes.getType(id); return new ResponseEntity<>(type.schema(), HttpStatus.OK); @@ -137,7 +140,8 @@ public class PolicyController { response = String.class, responseContainer = "List"), @ApiResponse(code = 404, message = "RIC is not found", response = String.class)}) - public ResponseEntity getPolicyTypes(@RequestParam(name = "ric", required = false) String ricName) { + public ResponseEntity getPolicyTypes(@ApiParam(name = "ric", required = false, value = "The name of " +// + "the Near-RT RIC to get types for.")@RequestParam(name = "ric", required = false) String ricName) { if (ricName == null) { Collection types = this.policyTypes.getAll(); return new ResponseEntity<>(toPolicyTypeIdsJson(types), HttpStatus.OK); @@ -159,7 +163,8 @@ public class PolicyController { @ApiResponse(code = 404, message = "Policy is not found")} // ) public ResponseEntity getPolicy( // - @RequestParam(name = "id", required = true) String id) { + @ApiParam(name = "id", required = true, value = "The ID of the policy instance.")@RequestParam(name = "id", // + required = true) String id) { try { Policy p = policies.getPolicy(id); return new ResponseEntity<>(p.json(), HttpStatus.OK); @@ -176,7 +181,8 @@ public class PolicyController { @ApiResponse(code = 404, message = "Policy is not found", response = String.class), @ApiResponse(code = 423, message = "RIC is not operational", response = String.class)}) public Mono> deletePolicy( // - @RequestParam(name = "id", required = true) String id) { + @ApiParam(name = "id", required = true, value = "The ID of the policy instance.")@RequestParam(name = "id", // + required = true) String id) { try { Policy policy = policies.getPolicy(id); keepServiceAlive(policy.ownerServiceName()); @@ -205,11 +211,18 @@ public class PolicyController { @ApiResponse(code = 404, message = "RIC or policy type is not found", response = String.class) // }) public Mono> putPolicy( // - @RequestParam(name = "type", required = false, defaultValue = "") String typeName, // - @RequestParam(name = "id", required = true) String instanceId, // - @RequestParam(name = "ric", required = true) String ricName, // - @RequestParam(name = "service", required = true) String service, // - @RequestParam(name = "transient", required = false, defaultValue = "false") boolean isTransient, // + @ApiParam(name = "type", required = false, value = "The name of the policy type.") // + @RequestParam(name = "type", required = false, defaultValue = "") String typeName, // + @ApiParam(name = "id", required = true, value = "The ID of the policy instance.")@RequestParam(name = "id", // + required = true) String instanceId, // + @ApiParam(name = "ric", required = true, value = "The name of the Near-RT RIC where the policy will be " +// + "created.")@RequestParam(name = "ric", required = true) String ricName, // + @ApiParam(name = "service", required = true, value = "The name of the service creating the policy.") // + @RequestParam(name = "service", required = true) String service, // + @ApiParam(name = "transient", required = false, value = "If the policy is transient or not (boolean " +// + "defaulted to false). A policy is transient if it will be forgotten when the service needs to " +// + "reconnect to the Near-RT RIC.")@RequestParam(name = "transient", required = false, // + defaultValue = "false") boolean isTransient, // @RequestBody Object jsonBody) { String jsonString = gson.toJson(jsonBody); @@ -300,9 +313,12 @@ public class PolicyController { @ApiResponse(code = 200, message = "Policies", response = PolicyInfo.class, responseContainer = "List"), @ApiResponse(code = 404, message = "RIC or type not found", response = String.class)}) public ResponseEntity getPolicies( // - @RequestParam(name = "type", required = false) String type, // - @RequestParam(name = "ric", required = false) String ric, // - @RequestParam(name = "service", required = false) String service) // + @ApiParam(name = "type", required = false, value = "The name of the policy type to get policies for.") // + @RequestParam(name = "type", required = false) String type, // + @ApiParam(name = "ric", required = false, value = "The name of the Near-RT RIC to get policies for.") // + @RequestParam(name = "ric", required = false) String ric, // + @ApiParam(name = "service", required = false, value = "The name of the service to get policies for.") // + @RequestParam(name = "service", required = false) String service) // { if ((type != null && this.policyTypes.get(type) == null)) { return new ResponseEntity<>("Policy type not found", HttpStatus.NOT_FOUND); @@ -321,9 +337,12 @@ public class PolicyController { value = {@ApiResponse(code = 200, message = "Policy ids", response = String.class, responseContainer = "List"), @ApiResponse(code = 404, message = "RIC or type not found", response = String.class)}) public ResponseEntity getPolicyIds( // - @RequestParam(name = "type", required = false) String type, // - @RequestParam(name = "ric", required = false) String ric, // - @RequestParam(name = "service", required = false) String service) // + @ApiParam(name = "type", required = false, value = "The name of the policy type to get policies for.") // + @RequestParam(name = "type", required = false) String type, // + @ApiParam(name = "ric", required = false, value = "The name of the Near-RT RIC to get policies for.") // + @RequestParam(name = "ric", required = false) String ric, // + @ApiParam(name = "service", required = false, value = "The name of the service to get policies for.") // + @RequestParam(name = "service", required = false) String service) // { if ((type != null && this.policyTypes.get(type) == null)) { return new ResponseEntity<>("Policy type not found", HttpStatus.NOT_FOUND); @@ -344,7 +363,8 @@ public class PolicyController { @ApiResponse(code = 404, message = "Policy is not found", response = String.class)} // ) public Mono> getPolicyStatus( // - @RequestParam(name = "id", required = true) String id) { + @ApiParam(name = "id", required = true, value = "The ID of the policy.")@RequestParam(name = "id", // + required = true) String id) { try { Policy policy = policies.getPolicy(id); -- 2.16.6