Jump to: navigation, search

OpenDaylight Controller:MD-SAL:Restconf API Explorer

MD-SAL 's RESTful interfaces are designed based on RESTCONF protocol (https://datatracker.ietf.org/doc/draft-bierman-netconf-restconf/). These interfaces are generated dynamically at runtime based on YANG models that defines its data. Since interface generation is dynamic, there are no statically compiled Java classes that can be annotated to create pretty documentation. The lack of documentation is one of the common complaints from users of MD-SAL.

RESTCONF API Explorer should address that complaint. It is deployed as an OSGI bundle that generates and renders the documentation at runtime. The generated documentation is based on Swagger specification (https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md) and is rendered on Swagger UI (https://github.com/wordnik/swagger-ui) which is embedded in this bundle.

Gerrit: https://git.opendaylight.org/gerrit/#/c/6574/
Video Presentation: http://youtu.be/QVmgC_dVAMQ

Usage

Getting resource listing

API explorer is accesible at

http://localhost:8080/apidoc/explorer

Karaf:

http://localhost:8181/apidoc/explorer/index.html
Fig 1

Replace localhost with IP of your controller, ofcourse! You should see UI like the one in Fig 1.

Resource List URL textbox is pre-populated with the URL. Press explore button to get the listing.

Note: This may take up to a min to load in your browser. Its just that server returns a lot of JSON documents for the browser to load. We'll add optimizations to make the loading time faster.

Once browser loads up the listing, any resource collection can be reviewed by expanding it (by clicking on it)

Working with a resource

Expanding a resource collection would list all supported resources (Fig 2). Any resource can further be examined by clicking on it (Fig 3).

Descriptions and Model definitions are generated from yang files.

HTML form is generated by swagger and is based on API Declaration Specification. Use this to execute the API and see request/response on live server. Fig 4 illustrates api request and response.

Dynamic doc generation

At runtime, this component queries MD-SAL to get access to Schema Service. Schema Service contains Schema Context that maintains a repository of all yang modules available in the system. Each module is then converted into swagger spec compliant json document. Restconf API Explorer exposes RESTful interfaces of its own to serve these JSON Document. The web ui uses these RESTful interfaces to render ui.

Restconf-doc.jpg

Implementation Details

There are 2 components in API Explorer.

  1. Web UI: This is Swagger UI embedded with this application
  2. API Doc Generator: This is a service that generates swagger compliant api documentation. It exposes 2 RESTFul endpoints
    1. Resource Listing : Returns a list of all yang modules in the system. Its accessible at /apidoc/apis
    2. API Declaration  : Returns all the resources defined per module. Its accessible at /apidocs/api/<module_name,revision>

This sequence diagram captures the flow.

Api-doc-generator.png

Further Improvements

NOTE: All of the issues listed below have meanwhile been closed.

Description Bug
Pagination and searching
The initial page load is extremely slow because it tries to load JSON for all the modules defined in the system. Need to have pagination and searching to limit the amount of JSON to be loaded by the browser.
https://bugs.opendaylight.org/show_bug.cgi?id=906
Augmentation Support
Currently URL for augmented nodes are not being generated.
https://bugs.opendaylight.org/show_bug.cgi?id=907
Implement Schema change listener
Whenever controller learns about a new yang schema, the documentation for it needs to be generated and cached.
https://bugs.opendaylight.org/show_bug.cgi?id=908
Generate Mount endpoints
RESTConf mount endpoints needs to be generated.
https://bugs.opendaylight.org/show_bug.cgi?id=910
JSON Conversion for YANG Identifier types
Model generator does not generate models for Identifier types
https://bugs.opendaylight.org/show_bug.cgi?id=909
Offline doc generation
Generate documentation during build time
https://bugs.opendaylight.org/show_bug.cgi?id=915
Highlight augmentations
Highlight the properties that are augmented and who augmented them.
https://bugs.opendaylight.org/show_bug.cgi?id=916
Highlight config attributes
Highlight config attributes in models
https://bugs.opendaylight.org/show_bug.cgi?id=931
Toaster URL is not correct
Its /config/toaster:toaster but should be toaster:toaster
https://bugs.opendaylight.org/show_bug.cgi?id=932