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