restconf/sal-rest-docgen/src/main/java/org/opendaylight/netconf/sal/rest/doc/model/builder/OperationBuilder.java

   1 /*
   2  * Copyright (c) 2020 PANTHEON.tech, s.r.o. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8
   9 package org.opendaylight.netconf.sal.rest.doc.model.builder;
  10
  11 import static org.opendaylight.netconf.sal.rest.doc.impl.DefinitionGenerator.INPUT;
  12 import static org.opendaylight.netconf.sal.rest.doc.impl.DefinitionGenerator.INPUT_SUFFIX;
  13 import static org.opendaylight.netconf.sal.rest.doc.impl.DefinitionGenerator.OUTPUT_SUFFIX;
  14
  15 import com.fasterxml.jackson.databind.node.ArrayNode;
  16 import com.fasterxml.jackson.databind.node.JsonNodeFactory;
  17 import com.fasterxml.jackson.databind.node.ObjectNode;
  18 import com.google.common.collect.ImmutableList;
  19 import java.util.List;
  20 import java.util.Optional;
  21 import javax.ws.rs.HttpMethod;
  22 import javax.ws.rs.core.MediaType;
  23 import javax.ws.rs.core.Response;
  24 import org.opendaylight.netconf.sal.rest.doc.impl.ApiDocServiceImpl.OAversion;
  25 import org.opendaylight.netconf.sal.rest.doc.impl.DefinitionNames;
  26 import org.opendaylight.netconf.sal.rest.doc.util.JsonUtil;
  27 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  28 import org.opendaylight.yangtools.yang.model.api.InputSchemaNode;
  29 import org.opendaylight.yangtools.yang.model.api.OperationDefinition;
  30 import org.opendaylight.yangtools.yang.model.api.OutputSchemaNode;
  31
  32 public final class OperationBuilder {
  33     public static final String BODY = "body";
  34     public static final String CONFIG = "_config";
  35     public static final String CONFIG_QUERY_PARAM = "config";
  36     public static final String CONSUMES_KEY = "consumes";
  37     public static final String CONTENT_KEY = "content";
  38     public static final String COMPONENTS_PREFIX = "#/components/schemas/";
  39     public static final String DEFINITIONS_PREFIX = "#/definitions/";
  40     public static final String DESCRIPTION_KEY = "description";
  41     public static final String IN_KEY = "in";
  42     public static final String INPUT_KEY = "input";
  43     public static final String NAME_KEY = "name";
  44     public static final String NONCONFIG_QUERY_PARAM = "nonconfig";
  45     public static final String PARAMETERS_KEY = "parameters";
  46     public static final String POST_SUFFIX = "_post";
  47     public static final String PROPERTIES_KEY = "properties";
  48     public static final String REF_KEY = "$ref";
  49     public static final String REQUEST_BODY_KEY = "requestBody";
  50     public static final String RESPONSES_KEY = "responses";
  51     public static final String SCHEMA_KEY = "schema";
  52     public static final String SUMMARY_KEY = "summary";
  53     public static final String SUMMARY_SEPARATOR = " - ";
  54     public static final String TAGS_KEY = "tags";
  55     public static final String TOP = "_TOP";
  56     public static final String XML_KEY = "xml";
  57     public static final String XML_SUFFIX = "_xml";
  58     private static final String CONTENT = "content";
  59     private static final ArrayNode CONSUMES_PUT_POST;
  60     private static final String ENUM_KEY = "enum";
  61     private static final List<String> MIME_TYPES = ImmutableList.of(MediaType.APPLICATION_XML,
  62             MediaType.APPLICATION_JSON);
  63     private static final String OBJECT = "object";
  64     private static final String REQUIRED_KEY = "required";
  65     private static final String STRING = "string";
  66     private static final String TYPE_KEY = "type";
  67     private static final String QUERY = "query";
  68
  69     static {
  70         CONSUMES_PUT_POST = JsonNodeFactory.instance.arrayNode();
  71         for (final String mimeType : MIME_TYPES) {
  72             CONSUMES_PUT_POST.add(mimeType);
  73         }
  74     }
  75
  76     private OperationBuilder() {
  77
  78     }
  79
  80     public static ObjectNode buildPost(final String parentName, final String nodeName, final String discriminator,
  81             final String moduleName, final Optional<String> deviceName, final String description,
  82             final ArrayNode pathParams, final OAversion oaversion) {
  83         final ObjectNode value = JsonNodeFactory.instance.objectNode();
  84         value.put(DESCRIPTION_KEY, description);
  85         value.put(SUMMARY_KEY, buildSummaryValue(HttpMethod.POST, moduleName, deviceName, nodeName));
  86         value.set(TAGS_KEY, buildTagsValue(deviceName, moduleName));
  87         final ArrayNode parameters = JsonUtil.copy(pathParams);
  88         final ObjectNode ref = JsonNodeFactory.instance.objectNode();
  89         final String cleanDefName = parentName + CONFIG + "_" + nodeName + POST_SUFFIX;
  90         final String defName = cleanDefName + discriminator;
  91         final String xmlDefName = cleanDefName + XML_SUFFIX + discriminator;
  92         ref.put(REF_KEY, getAppropriateModelPrefix(oaversion) + defName);
  93         insertRequestBodyParameter(parameters, value, defName, xmlDefName, nodeName + CONFIG, oaversion);
  94         value.set(PARAMETERS_KEY, parameters);
  95
  96         final ObjectNode responses = JsonNodeFactory.instance.objectNode();
  97         responses.set(String.valueOf(Response.Status.CREATED.getStatusCode()),
  98                 buildResponse(Response.Status.CREATED.getReasonPhrase(), Optional.empty(), oaversion));
  99
 100         value.set(RESPONSES_KEY, responses);
 101         setConsumesIfNeeded(value, oaversion);
 102         return value;
 103     }
 104
 105     public static ObjectNode buildGet(final DataSchemaNode node, final String moduleName,
 106             final Optional<String> deviceName, final ArrayNode pathParams, final String defName,
 107             final boolean isConfig, final OAversion oaversion) {
 108         final ObjectNode value = JsonNodeFactory.instance.objectNode();
 109         value.put(DESCRIPTION_KEY, node.getDescription().orElse(""));
 110         value.put(SUMMARY_KEY, buildSummaryValue(HttpMethod.GET, moduleName, deviceName,
 111                 node.getQName().getLocalName()));
 112         value.set(TAGS_KEY, buildTagsValue(deviceName, moduleName));
 113         final ArrayNode parameters = JsonUtil.copy(pathParams);
 114
 115         addQueryParameters(parameters, isConfig, oaversion);
 116
 117         value.set(PARAMETERS_KEY, parameters);
 118
 119         final ObjectNode responses = JsonNodeFactory.instance.objectNode();
 120         final ObjectNode schema = JsonNodeFactory.instance.objectNode();
 121         schema.put(REF_KEY, getAppropriateModelPrefix(oaversion) + defName);
 122         responses.set(String.valueOf(Response.Status.OK.getStatusCode()),
 123                 buildResponse(Response.Status.OK.getReasonPhrase(), Optional.of(schema), oaversion));
 124
 125         value.set(RESPONSES_KEY, responses);
 126         return value;
 127     }
 128
 129     private static void addQueryParameters(final ArrayNode parameters, final boolean isConfig,
 130             final OAversion oaversion) {
 131         final ObjectNode contentParam = JsonNodeFactory.instance.objectNode();
 132         final ArrayNode cases = JsonNodeFactory.instance.arrayNode();
 133         cases.add(NONCONFIG_QUERY_PARAM);
 134         if (isConfig) {
 135             cases.add(CONFIG_QUERY_PARAM);
 136         } else {
 137             contentParam.put(REQUIRED_KEY, true);
 138         }
 139         contentParam.put(IN_KEY, QUERY);
 140         contentParam.put(NAME_KEY, CONTENT);
 141
 142         final ObjectNode typeParent = getTypeParentNode(contentParam, oaversion);
 143         typeParent.put(TYPE_KEY, STRING);
 144         typeParent.set(ENUM_KEY, cases);
 145
 146         parameters.add(contentParam);
 147     }
 148
 149     public static ObjectNode buildPut(final String parentName, final String nodeName, final String discriminator,
 150             final String moduleName, final Optional<String> deviceName, final String description,
 151             final ArrayNode pathParams, final OAversion oaversion) {
 152         final ObjectNode value = JsonNodeFactory.instance.objectNode();
 153         value.put(DESCRIPTION_KEY, description);
 154         value.put(SUMMARY_KEY, buildSummaryValue(HttpMethod.PUT, moduleName, deviceName, nodeName));
 155         value.set(TAGS_KEY, buildTagsValue(deviceName, moduleName));
 156         final ArrayNode parameters = JsonUtil.copy(pathParams);
 157         final String defName = parentName + CONFIG + "_" + nodeName + TOP;
 158         final String xmlDefName = parentName + CONFIG + "_" + nodeName;
 159         insertRequestBodyParameter(parameters, value, defName, xmlDefName, nodeName + CONFIG, oaversion);
 160         value.set(PARAMETERS_KEY, parameters);
 161
 162         final ObjectNode responses = JsonNodeFactory.instance.objectNode();
 163         responses.set(String.valueOf(Response.Status.CREATED.getStatusCode()),
 164                 buildResponse(Response.Status.CREATED.getReasonPhrase(), Optional.empty(), oaversion));
 165         responses.set(String.valueOf(Response.Status.NO_CONTENT.getStatusCode()),
 166                 buildResponse("Updated", Optional.empty(), oaversion));
 167
 168         value.set(RESPONSES_KEY, responses);
 169         setConsumesIfNeeded(value, oaversion);
 170         return value;
 171     }
 172
 173     public static ObjectNode buildDelete(final DataSchemaNode node, final String moduleName,
 174             final Optional<String> deviceName, final ArrayNode pathParams, final OAversion oaversion) {
 175         final ObjectNode value = JsonNodeFactory.instance.objectNode();
 176         value.put(SUMMARY_KEY, buildSummaryValue(HttpMethod.DELETE, moduleName, deviceName,
 177                 node.getQName().getLocalName()));
 178         value.set(TAGS_KEY, buildTagsValue(deviceName, moduleName));
 179         value.put(DESCRIPTION_KEY, node.getDescription().orElse(""));
 180         final ArrayNode parameters = JsonUtil.copy(pathParams);
 181         value.set(PARAMETERS_KEY, parameters);
 182
 183         final ObjectNode responses = JsonNodeFactory.instance.objectNode();
 184         responses.set(String.valueOf(Response.Status.NO_CONTENT.getStatusCode()),
 185                 buildResponse("Deleted", Optional.empty(), oaversion));
 186
 187         value.set(RESPONSES_KEY, responses);
 188         return value;
 189     }
 190
 191     public static ObjectNode buildPostOperation(final OperationDefinition operDef, final String moduleName,
 192             final Optional<String> deviceName, final String parentName, final DefinitionNames definitionNames,
 193             final OAversion oaversion) {
 194         final ObjectNode postOperation = JsonNodeFactory.instance.objectNode();
 195         final ArrayNode parameters = JsonNodeFactory.instance.arrayNode();
 196         final String operName = operDef.getQName().getLocalName();
 197         final String inputName = operName + INPUT_SUFFIX;
 198
 199         final InputSchemaNode input = operDef.getInput();
 200         final OutputSchemaNode output = operDef.getOutput();
 201         if (!input.getChildNodes().isEmpty()) {
 202             final String discriminator = definitionNames.getDiscriminator(input);
 203             final String clearDefName = parentName + "_" + operName + INPUT_SUFFIX;
 204             final String defName = clearDefName + discriminator;
 205             final String defTopName = clearDefName + TOP + discriminator;
 206             insertRequestBodyParameter(parameters, postOperation, defTopName, defName, inputName, oaversion);
 207         } else {
 208             final ObjectNode payload = JsonNodeFactory.instance.objectNode();
 209             final ObjectNode jsonSchema = JsonNodeFactory.instance.objectNode();
 210             final ObjectNode properties = JsonNodeFactory.instance.objectNode();
 211             final ObjectNode inputSchema = JsonNodeFactory.instance.objectNode();
 212             inputSchema.put(TYPE_KEY, OBJECT);
 213             properties.set(INPUT_KEY, inputSchema);
 214             jsonSchema.put(TYPE_KEY, OBJECT);
 215             jsonSchema.set(PROPERTIES_KEY, properties);
 216             if (oaversion.equals(OAversion.V3_0)) {
 217                 final ObjectNode content = JsonNodeFactory.instance.objectNode();
 218                 final ObjectNode jsonTypeValue = JsonNodeFactory.instance.objectNode();
 219                 jsonTypeValue.set(SCHEMA_KEY, jsonSchema);
 220                 content.set(MediaType.APPLICATION_JSON, jsonTypeValue);
 221
 222                 final ObjectNode xmlSchema = JsonNodeFactory.instance.objectNode();
 223                 xmlSchema.put(TYPE_KEY, OBJECT);
 224                 final ObjectNode xml = JsonNodeFactory.instance.objectNode();
 225                 xml.put(NAME_KEY, INPUT);
 226                 xmlSchema.set(XML_KEY, xml);
 227                 final ObjectNode xmlTypeValue = JsonNodeFactory.instance.objectNode();
 228                 xmlTypeValue.set(SCHEMA_KEY, xmlSchema);
 229                 content.set(MediaType.APPLICATION_XML, xmlTypeValue);
 230
 231                 payload.set(CONTENT_KEY, content);
 232                 payload.put(DESCRIPTION_KEY, inputName);
 233                 postOperation.set(REQUEST_BODY_KEY, payload);
 234             } else {
 235                 payload.put(IN_KEY, BODY);
 236                 payload.put(NAME_KEY, inputName);
 237                 payload.set(SCHEMA_KEY, jsonSchema);
 238                 parameters.add(payload);
 239             }
 240
 241         }
 242         setConsumesIfNeeded(postOperation, oaversion);
 243         postOperation.set(PARAMETERS_KEY, parameters);
 244         final ObjectNode responses = JsonNodeFactory.instance.objectNode();
 245         final String description = String.format("RPC %s success", operName);
 246
 247         if (!output.getChildNodes().isEmpty()) {
 248             final ObjectNode schema = JsonNodeFactory.instance.objectNode();
 249             final String defName = parentName + "_" + operName + OUTPUT_SUFFIX + TOP
 250                     + definitionNames.getDiscriminator(output);
 251             schema.put(REF_KEY, getAppropriateModelPrefix(oaversion) + defName);
 252             responses.set(String.valueOf(Response.Status.OK.getStatusCode()), buildResponse(description,
 253                     Optional.of(schema), oaversion));
 254         } else {
 255             responses.set(String.valueOf(Response.Status.NO_CONTENT.getStatusCode()), buildResponse(description,
 256                     Optional.empty(), oaversion));
 257         }
 258         postOperation.set(RESPONSES_KEY, responses);
 259         postOperation.put(DESCRIPTION_KEY, operDef.getDescription().orElse(""));
 260         postOperation.put(SUMMARY_KEY, buildSummaryValue(HttpMethod.POST, moduleName, deviceName, operName));
 261         postOperation.set(TAGS_KEY, buildTagsValue(deviceName, moduleName));
 262         return postOperation;
 263     }
 264
 265     private static void insertRequestBodyParameter(final ArrayNode parameters, final ObjectNode operation,
 266             final String defName, final String xmlDefName, final String name, final OAversion oaversion) {
 267         final ObjectNode payload = JsonNodeFactory.instance.objectNode();
 268         if (oaversion.equals(OAversion.V3_0)) {
 269             final ObjectNode content = JsonNodeFactory.instance.objectNode();
 270             content.set(MediaType.APPLICATION_JSON, buildMimeTypeValue(defName));
 271             content.set(MediaType.APPLICATION_XML, buildMimeTypeValue(xmlDefName));
 272             payload.set(CONTENT_KEY, content);
 273             payload.put(DESCRIPTION_KEY, name);
 274             operation.set(REQUEST_BODY_KEY, payload);
 275         } else {
 276             payload.put(IN_KEY, BODY);
 277             payload.put(NAME_KEY, name);
 278             payload.set(SCHEMA_KEY, buildRefSchema(defName, OAversion.V2_0));
 279             parameters.add(payload);
 280         }
 281     }
 282
 283     private static ObjectNode buildRefSchema(final String defName, final OAversion oaversion) {
 284         final ObjectNode schema = JsonNodeFactory.instance.objectNode();
 285         schema.put(REF_KEY, getAppropriateModelPrefix(oaversion) + defName);
 286         return schema;
 287     }
 288
 289     private static ObjectNode buildMimeTypeValue(final String defName) {
 290         final ObjectNode mimeTypeValue = JsonNodeFactory.instance.objectNode();
 291         mimeTypeValue.set(SCHEMA_KEY, buildRefSchema(defName, OAversion.V3_0));
 292         return mimeTypeValue;
 293     }
 294
 295     public static ObjectNode buildResponse(final String description, final Optional<ObjectNode> schema,
 296             final OAversion oaversion) {
 297         final ObjectNode response = JsonNodeFactory.instance.objectNode();
 298
 299         if (schema.isPresent()) {
 300             final ObjectNode schemaValue = schema.get();
 301             if (oaversion.equals(OAversion.V3_0)) {
 302                 final ObjectNode content = JsonNodeFactory.instance.objectNode();
 303                 final ObjectNode body = JsonNodeFactory.instance.objectNode();
 304                 for (final String mimeType : MIME_TYPES) {
 305                     content.set(mimeType, body);
 306                 }
 307                 body.set(SCHEMA_KEY, schemaValue);
 308                 response.set(CONTENT_KEY, content);
 309             } else {
 310                 response.set(SCHEMA_KEY, schemaValue);
 311             }
 312         }
 313         response.put(DESCRIPTION_KEY, description);
 314         return response;
 315     }
 316
 317     private static void setConsumesIfNeeded(final ObjectNode operation, final OAversion oaversion) {
 318         if (oaversion.equals(OAversion.V2_0)) {
 319             operation.set(CONSUMES_KEY, CONSUMES_PUT_POST);
 320         }
 321     }
 322
 323     private static String buildSummaryValue(final String httpMethod, final String moduleName,
 324             final Optional<String> deviceName, final String nodeName) {
 325         return httpMethod + SUMMARY_SEPARATOR + deviceName.map(s -> s + SUMMARY_SEPARATOR).orElse("")
 326                 + moduleName + SUMMARY_SEPARATOR + nodeName;
 327     }
 328
 329     public static ArrayNode buildTagsValue(final Optional<String> deviceName, final String moduleName) {
 330         final ArrayNode tagsValue = JsonNodeFactory.instance.arrayNode();
 331         tagsValue.add(deviceName.map(s -> "mounted " + s).orElse("controller") + " " + moduleName);
 332         return tagsValue;
 333     }
 334
 335     public static String getAppropriateModelPrefix(final OAversion oaversion) {
 336         if (oaversion.equals(OAversion.V3_0)) {
 337             return COMPONENTS_PREFIX;
 338         }
 339         return DEFINITIONS_PREFIX;
 340     }
 341
 342     public static ObjectNode getTypeParentNode(final ObjectNode parameter, final OAversion oaversion) {
 343         if (oaversion.equals(OAversion.V3_0)) {
 344             final ObjectNode schema = JsonNodeFactory.instance.objectNode();
 345             parameter.set(SCHEMA_KEY, schema);
 346             return schema;
 347         }
 348         return parameter;
 349     }
 350 }