restconf/sal-rest-docgen/src/main/java/org/opendaylight/netconf/sal/rest/doc/impl/BaseYangSwaggerGenerator.java

   1 /*
   2  * Copyright (c) 2014 Brocade Communications Systems, Inc. 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 package org.opendaylight.netconf.sal.rest.doc.impl;
   9
  10 import static org.opendaylight.netconf.sal.rest.doc.util.RestDocgenUtil.resolvePathArgumentsName;
  11
  12 import com.fasterxml.jackson.databind.ObjectMapper;
  13 import com.fasterxml.jackson.databind.SerializationFeature;
  14 import com.fasterxml.jackson.databind.node.ObjectNode;
  15 import com.google.common.base.Preconditions;
  16 import java.io.IOException;
  17 import java.net.URI;
  18 import java.time.format.DateTimeParseException;
  19 import java.util.ArrayList;
  20 import java.util.Arrays;
  21 import java.util.Collection;
  22 import java.util.Collections;
  23 import java.util.List;
  24 import java.util.Map.Entry;
  25 import java.util.Optional;
  26 import java.util.Set;
  27 import java.util.SortedSet;
  28 import java.util.TreeSet;
  29 import javax.ws.rs.core.UriInfo;
  30 import org.opendaylight.controller.sal.core.api.model.SchemaService;
  31 import org.opendaylight.netconf.sal.rest.doc.model.builder.OperationBuilder;
  32 import org.opendaylight.netconf.sal.rest.doc.model.builder.OperationBuilder.Delete;
  33 import org.opendaylight.netconf.sal.rest.doc.model.builder.OperationBuilder.Get;
  34 import org.opendaylight.netconf.sal.rest.doc.model.builder.OperationBuilder.Post;
  35 import org.opendaylight.netconf.sal.rest.doc.model.builder.OperationBuilder.Put;
  36 import org.opendaylight.netconf.sal.rest.doc.swagger.Api;
  37 import org.opendaylight.netconf.sal.rest.doc.swagger.ApiDeclaration;
  38 import org.opendaylight.netconf.sal.rest.doc.swagger.Operation;
  39 import org.opendaylight.netconf.sal.rest.doc.swagger.Parameter;
  40 import org.opendaylight.netconf.sal.rest.doc.swagger.Resource;
  41 import org.opendaylight.netconf.sal.rest.doc.swagger.ResourceList;
  42 import org.opendaylight.yangtools.yang.common.QName;
  43 import org.opendaylight.yangtools.yang.common.Revision;
  44 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  45 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates;
  46 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  47 import org.opendaylight.yangtools.yang.model.api.ContainerSchemaNode;
  48 import org.opendaylight.yangtools.yang.model.api.DataNodeContainer;
  49 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  50 import org.opendaylight.yangtools.yang.model.api.ListSchemaNode;
  51 import org.opendaylight.yangtools.yang.model.api.Module;
  52 import org.opendaylight.yangtools.yang.model.api.RpcDefinition;
  53 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
  54 import org.slf4j.Logger;
  55 import org.slf4j.LoggerFactory;
  56
  57 public abstract class BaseYangSwaggerGenerator {
  58
  59     private static final Logger LOG = LoggerFactory.getLogger(BaseYangSwaggerGenerator.class);
  60
  61     protected static final String API_VERSION = "1.0.0";
  62     protected static final String SWAGGER_VERSION = "1.2";
  63
  64     static final String MODULE_NAME_SUFFIX = "_module";
  65     private final ModelGenerator jsonConverter = new ModelGenerator();
  66
  67     // private Map<String, ApiDeclaration> MODULE_DOC_CACHE = new HashMap<>()
  68     private final ObjectMapper mapper = new ObjectMapper();
  69     private final SchemaService schemaService;
  70
  71     protected BaseYangSwaggerGenerator(Optional<SchemaService> schemaService) {
  72         this.schemaService = schemaService.orElse(null);
  73         this.mapper.configure(SerializationFeature.INDENT_OUTPUT, true);
  74     }
  75
  76     public SchemaService getSchemaService() {
  77         return schemaService;
  78     }
  79
  80     public ResourceList getResourceListing(final UriInfo uriInfo) {
  81         final SchemaContext schemaContext = schemaService.getGlobalContext();
  82         Preconditions.checkState(schemaContext != null);
  83         return getResourceListing(uriInfo, schemaContext, "");
  84     }
  85
  86     /**
  87      * Return list of modules converted to swagger compliant resource list.
  88      */
  89     public ResourceList getResourceListing(final UriInfo uriInfo, final SchemaContext schemaContext,
  90             final String context) {
  91
  92         final ResourceList resourceList = createResourceList();
  93
  94         final Set<Module> modules = getSortedModules(schemaContext);
  95
  96         final List<Resource> resources = new ArrayList<>(modules.size());
  97
  98         LOG.info("Modules found [{}]", modules.size());
  99
 100         for (final Module module : modules) {
 101             final String revisionString = module.getQNameModule().getRevision().map(Revision::toString).orElse(null);
 102             final Resource resource = new Resource();
 103             LOG.debug("Working on [{},{}]...", module.getName(), revisionString);
 104             final ApiDeclaration doc =
 105                     getApiDeclaration(module.getName(), revisionString, uriInfo, schemaContext, context);
 106
 107             if (doc != null) {
 108                 resource.setPath(generatePath(uriInfo, module.getName(), revisionString));
 109                 resources.add(resource);
 110             } else {
 111                 LOG.warn("Could not generate doc for {},{}", module.getName(), revisionString);
 112             }
 113         }
 114
 115         resourceList.setApis(resources);
 116
 117         return resourceList;
 118     }
 119
 120     public ResourceList createResourceList() {
 121         final ResourceList resourceList = new ResourceList();
 122         resourceList.setApiVersion(API_VERSION);
 123         resourceList.setSwaggerVersion(SWAGGER_VERSION);
 124         return resourceList;
 125     }
 126
 127     public String generatePath(final UriInfo uriInfo, final String name, final String revision) {
 128         final URI uri = uriInfo.getRequestUriBuilder().path(generateCacheKey(name, revision)).build();
 129         return uri.toASCIIString();
 130     }
 131
 132     public ApiDeclaration getApiDeclaration(final String module, final String revision, final UriInfo uriInfo) {
 133         final SchemaContext schemaContext = schemaService.getGlobalContext();
 134         Preconditions.checkState(schemaContext != null);
 135         return getApiDeclaration(module, revision, uriInfo, schemaContext, "");
 136     }
 137
 138     public ApiDeclaration getApiDeclaration(final String moduleName, final String revision, final UriInfo uriInfo,
 139             final SchemaContext schemaContext, final String context) {
 140         final Optional<Revision> rev;
 141
 142         try {
 143             rev = Revision.ofNullable(revision);
 144         } catch (final DateTimeParseException e) {
 145             throw new IllegalArgumentException(e);
 146         }
 147
 148         final Module module = schemaContext.findModule(moduleName, rev).orElse(null);
 149         Preconditions.checkArgument(module != null,
 150                 "Could not find module by name,revision: " + moduleName + "," + revision);
 151
 152         return getApiDeclaration(module, uriInfo, context, schemaContext);
 153     }
 154
 155     public ApiDeclaration getApiDeclaration(final Module module, final UriInfo uriInfo,
 156             final String context, final SchemaContext schemaContext) {
 157         final String basePath = createBasePathFromUriInfo(uriInfo);
 158
 159         final ApiDeclaration doc = getSwaggerDocSpec(module, basePath, context, schemaContext);
 160         if (doc != null) {
 161             return doc;
 162         }
 163         return null;
 164     }
 165
 166     public String createBasePathFromUriInfo(final UriInfo uriInfo) {
 167         String portPart = "";
 168         final int port = uriInfo.getBaseUri().getPort();
 169         if (port != -1) {
 170             portPart = ":" + port;
 171         }
 172         final String basePath =
 173                 new StringBuilder(uriInfo.getBaseUri().getScheme()).append("://").append(uriInfo.getBaseUri().getHost())
 174                         .append(portPart).toString();
 175         return basePath;
 176     }
 177
 178     public ApiDeclaration getSwaggerDocSpec(final Module module, final String basePath, final String context,
 179                                             final SchemaContext schemaContext) {
 180         final ApiDeclaration doc = createApiDeclaration(basePath);
 181
 182         final List<Api> apis = new ArrayList<>();
 183         boolean hasAddRootPostLink = false;
 184
 185         final Collection<DataSchemaNode> dataSchemaNodes = module.getChildNodes();
 186         LOG.debug("child nodes size [{}]", dataSchemaNodes.size());
 187         for (final DataSchemaNode node : dataSchemaNodes) {
 188             if (node instanceof ListSchemaNode || node instanceof ContainerSchemaNode) {
 189                 LOG.debug("Is Configuration node [{}] [{}]", node.isConfiguration(), node.getQName().getLocalName());
 190
 191                 List<Parameter> pathParams = new ArrayList<>();
 192                 String resourcePath;
 193
 194                 /*
 195                  * Only when the node's config statement is true, such apis as
 196                  * GET/PUT/POST/DELETE config are added for this node.
 197                  */
 198                 if (node.isConfiguration()) { // This node's config statement is
 199                                               // true.
 200                     resourcePath = getDataStorePath("config", context);
 201
 202                     /*
 203                      * When there are two or more top container or list nodes
 204                      * whose config statement is true in module, make sure that
 205                      * only one root post link is added for this module.
 206                      */
 207                     if (!hasAddRootPostLink) {
 208                         LOG.debug("Has added root post link for module {}", module.getName());
 209                         addRootPostLink(module, (DataNodeContainer) node, pathParams, resourcePath, "config", apis);
 210
 211                         hasAddRootPostLink = true;
 212                     }
 213
 214                     addApis(node, apis, resourcePath, pathParams, schemaContext, true, module.getName(), "config");
 215                 }
 216                 pathParams = new ArrayList<>();
 217                 resourcePath = getDataStorePath("operational", context);
 218
 219                 addApis(node, apis, resourcePath, pathParams, schemaContext, false, module.getName(), "operational");
 220             }
 221         }
 222
 223         final Set<RpcDefinition> rpcs = module.getRpcs();
 224         for (final RpcDefinition rpcDefinition : rpcs) {
 225             final String resourcePath;
 226             resourcePath = getDataStorePath("operations", context);
 227
 228             addRpcs(rpcDefinition, apis, resourcePath, schemaContext);
 229         }
 230
 231         LOG.debug("Number of APIs found [{}]", apis.size());
 232
 233         if (!apis.isEmpty()) {
 234             doc.setApis(apis);
 235             ObjectNode models = null;
 236
 237             try {
 238                 models = this.jsonConverter.convertToJsonSchema(module, schemaContext);
 239                 doc.setModels(models);
 240                 if (LOG.isDebugEnabled()) {
 241                     LOG.debug(this.mapper.writeValueAsString(doc));
 242                 }
 243             } catch (IOException e) {
 244                 LOG.error("Exception occured in ModelGenerator", e);
 245             }
 246
 247             return doc;
 248         }
 249         return null;
 250     }
 251
 252     private void addRootPostLink(final Module module, final DataNodeContainer node,
 253             final List<Parameter> pathParams, final String resourcePath, final String dataStore, final List<Api> apis) {
 254         if (containsListOrContainer(module.getChildNodes())) {
 255             final Api apiForRootPostUri = new Api();
 256             apiForRootPostUri.setPath(resourcePath.concat(getContent(dataStore)));
 257             apiForRootPostUri.setOperations(operationPost(module.getName() + MODULE_NAME_SUFFIX,
 258                     module.getDescription().orElse(null), module, pathParams, true, ""));
 259             apis.add(apiForRootPostUri);
 260         }
 261     }
 262
 263     public ApiDeclaration createApiDeclaration(final String basePath) {
 264         final ApiDeclaration doc = new ApiDeclaration();
 265         doc.setApiVersion(API_VERSION);
 266         doc.setSwaggerVersion(SWAGGER_VERSION);
 267         doc.setBasePath(basePath);
 268         doc.setProduces(Arrays.asList("application/json", "application/xml"));
 269         return doc;
 270     }
 271
 272     public abstract String getDataStorePath(String dataStore, String context);
 273
 274     private static String generateCacheKey(final String module, final String revision) {
 275         return module + "(" + revision + ")";
 276     }
 277
 278     private void addApis(final DataSchemaNode node, final List<Api> apis, final String parentPath,
 279             final List<Parameter> parentPathParams, final SchemaContext schemaContext, final boolean addConfigApi,
 280             final String parentName, final String dataStore) {
 281         final Api api = new Api();
 282         final List<Parameter> pathParams = new ArrayList<>(parentPathParams);
 283
 284         final String resourcePath = parentPath + "/" + createPath(node, pathParams, schemaContext);
 285         LOG.debug("Adding path: [{}]", resourcePath);
 286         api.setPath(resourcePath.concat(getContent(dataStore)));
 287
 288         Iterable<DataSchemaNode> childSchemaNodes = Collections.<DataSchemaNode>emptySet();
 289         if (node instanceof ListSchemaNode || node instanceof ContainerSchemaNode) {
 290             final DataNodeContainer dataNodeContainer = (DataNodeContainer) node;
 291             childSchemaNodes = dataNodeContainer.getChildNodes();
 292         }
 293         api.setOperations(operation(node, pathParams, addConfigApi, childSchemaNodes, parentName));
 294         apis.add(api);
 295
 296         for (final DataSchemaNode childNode : childSchemaNodes) {
 297             if (childNode instanceof ListSchemaNode || childNode instanceof ContainerSchemaNode) {
 298                 // keep config and operation attributes separate.
 299                 if (childNode.isConfiguration() == addConfigApi) {
 300                     final String newParent = parentName + "/" + node.getQName().getLocalName();
 301                     addApis(childNode, apis, resourcePath, pathParams, schemaContext, addConfigApi, newParent,
 302                             dataStore);
 303                 }
 304             }
 305         }
 306     }
 307
 308     public abstract String getContent(String dataStore);
 309
 310     private static boolean containsListOrContainer(final Iterable<DataSchemaNode> nodes) {
 311         for (final DataSchemaNode child : nodes) {
 312             if (child instanceof ListSchemaNode || child instanceof ContainerSchemaNode) {
 313                 return true;
 314             }
 315         }
 316         return false;
 317     }
 318
 319     private static List<Operation> operation(final DataSchemaNode node, final List<Parameter> pathParams,
 320             final boolean isConfig, final Iterable<DataSchemaNode> childSchemaNodes, final String parentName) {
 321         final List<Operation> operations = new ArrayList<>();
 322
 323         final Get getBuilder = new Get(node, isConfig);
 324         operations.add(getBuilder.pathParams(pathParams).build());
 325
 326         if (isConfig) {
 327             final Put putBuilder = new Put(node.getQName().getLocalName(), node.getDescription().orElse(null),
 328                 parentName);
 329             operations.add(putBuilder.pathParams(pathParams).build());
 330
 331             final Delete deleteBuilder = new Delete(node);
 332             operations.add(deleteBuilder.pathParams(pathParams).build());
 333
 334             if (containsListOrContainer(childSchemaNodes)) {
 335                 operations.addAll(operationPost(node.getQName().getLocalName(), node.getDescription().orElse(null),
 336                         (DataNodeContainer) node, pathParams, isConfig, parentName + "/"));
 337             }
 338         }
 339         return operations;
 340     }
 341
 342     private static List<Operation> operationPost(final String name, final String description,
 343             final DataNodeContainer dataNodeContainer, final List<Parameter> pathParams, final boolean isConfig,
 344             final String parentName) {
 345         final List<Operation> operations = new ArrayList<>();
 346         if (isConfig) {
 347             final Post postBuilder = new Post(name, parentName + name, description, dataNodeContainer);
 348             operations.add(postBuilder.pathParams(pathParams).build());
 349         }
 350         return operations;
 351     }
 352
 353     protected abstract ListPathBuilder newListPathBuilder();
 354
 355     private String createPath(final DataSchemaNode schemaNode, final List<Parameter> pathParams,
 356             final SchemaContext schemaContext) {
 357         final StringBuilder path = new StringBuilder();
 358         final String localName = resolvePathArgumentsName(schemaNode, schemaContext);
 359         path.append(localName);
 360
 361         if (schemaNode instanceof ListSchemaNode) {
 362             final List<QName> listKeys = ((ListSchemaNode) schemaNode).getKeyDefinition();
 363             for (final QName listKey : listKeys) {
 364                 final ListPathBuilder keyBuilder = newListPathBuilder();
 365                 final DataSchemaNode dataChildByName = ((DataNodeContainer) schemaNode).getDataChildByName(listKey);
 366                 final String pathParamIdentifier = keyBuilder.nextParamIdentifier(listKey.getLocalName());
 367
 368                 path.append(pathParamIdentifier);
 369
 370                 final Parameter pathParam = new Parameter();
 371                 pathParam.setName(listKey.getLocalName());
 372                 pathParam.setDescription(dataChildByName.getDescription().orElse(null));
 373                 pathParam.setType("string");
 374                 pathParam.setParamType("path");
 375
 376                 pathParams.add(pathParam);
 377             }
 378         }
 379         return path.toString();
 380     }
 381
 382     protected void addRpcs(final RpcDefinition rpcDefn, final List<Api> apis, final String parentPath,
 383             final SchemaContext schemaContext) {
 384         final Api rpc = new Api();
 385         final String resourcePath = parentPath + "/" + resolvePathArgumentsName(rpcDefn, schemaContext);
 386         rpc.setPath(resourcePath);
 387
 388         final Operation operationSpec = new Operation();
 389         operationSpec.setMethod("POST");
 390         operationSpec.setNotes(rpcDefn.getDescription().orElse(null));
 391         operationSpec.setNickname(rpcDefn.getQName().getLocalName());
 392         if (!rpcDefn.getOutput().getChildNodes().isEmpty()) {
 393             operationSpec.setType("(" + rpcDefn.getQName().getLocalName() + ")output" + OperationBuilder.TOP);
 394         }
 395         if (!rpcDefn.getInput().getChildNodes().isEmpty()) {
 396             final Parameter payload = new Parameter();
 397             payload.setParamType("body");
 398             payload.setType("(" + rpcDefn.getQName().getLocalName() + ")input" + OperationBuilder.TOP);
 399             operationSpec.setParameters(Collections.singletonList(payload));
 400             operationSpec.setConsumes(OperationBuilder.CONSUMES_PUT_POST);
 401         }
 402
 403         rpc.setOperations(Arrays.asList(operationSpec));
 404
 405         apis.add(rpc);
 406     }
 407
 408     protected SortedSet<Module> getSortedModules(final SchemaContext schemaContext) {
 409         if (schemaContext == null) {
 410             return new TreeSet<>();
 411         }
 412
 413         final Set<Module> modules = schemaContext.getModules();
 414
 415         final SortedSet<Module> sortedModules = new TreeSet<>((module1, module2) -> {
 416             int result = module1.getName().compareTo(module2.getName());
 417             if (result == 0) {
 418                 result = Revision.compare(module1.getRevision(), module2.getRevision());
 419             }
 420             if (result == 0) {
 421                 result = module1.getNamespace().compareTo(module2.getNamespace());
 422             }
 423             return result;
 424         });
 425         for (final Module m : modules) {
 426             if (m != null) {
 427                 sortedModules.add(m);
 428             }
 429         }
 430         return sortedModules;
 431     }
 432
 433     protected abstract void appendPathKeyValue(StringBuilder builder, Object value);
 434
 435     public String generateUrlPrefixFromInstanceID(final YangInstanceIdentifier key, final String moduleName) {
 436         final StringBuilder builder = new StringBuilder();
 437         builder.append("/");
 438         if (moduleName != null) {
 439             builder.append(moduleName).append(':');
 440         }
 441         for (final PathArgument arg : key.getPathArguments()) {
 442             final String name = arg.getNodeType().getLocalName();
 443             if (arg instanceof YangInstanceIdentifier.NodeIdentifierWithPredicates) {
 444                 final NodeIdentifierWithPredicates nodeId = (NodeIdentifierWithPredicates) arg;
 445                 for (final Entry<QName, Object> entry : nodeId.getKeyValues().entrySet()) {
 446                     appendPathKeyValue(builder, entry.getValue());
 447                 }
 448             } else {
 449                 builder.append(name).append('/');
 450             }
 451         }
 452         return builder.toString();
 453     }
 454
 455     protected interface ListPathBuilder {
 456         String nextParamIdentifier(String key);
 457     }
 458 }