Page tree

Have questions? Stuck? Please check our FAQ for some common questions and answers.

Skip to end of metadata
Go to start of metadata

REST API Documentation (Swagger)

Swagger UI is a tool to visualize and document REST API's in a sandbox environment. The resource reads in the API specification from a single JSON file which is generated through the OnosSwaggerMojo class under the onos-maven-plugin. The OnosSwaggerMojo class allows flexibility by using QDox to sweep through API resource files and process annotations (JAX-RS and Javadocs) to build the JSON file using consumed by Swagger UI.

Creating the Documentation 

OnosSwaggerMojo begins by looking for a "@path" annotation to decide whether a class contains REST API's. If it finds one it then:

  • Creates a tag for the class so that all API's underneath a class are grouped together 
  • Searches through each method looking for API methods and documenting
    • Method type (Get, Post, Put, Delete), summary, description, tags (which class it belongs to) 
    • Parameters: in (Path, Query, or Body), descriptions, type (String, integer, number, boolean), required
    • Swagger json schema: @onos.rsModel <Json_schema_file_name_without_extension> javadoc annotation and a .json schema file in the dircrectory <app_path>/src/main/resources/definitions. An example can be seen with the DHCP app.
  • Responses: Types of response codes returned and their associated meanings
  • Produces/consumes: application type returned or consumed by the API (ex. "application/json")

The JSON file is written to onos/web/api/target/classes/SwaggerConfig/SwaggerConfileFile.json

For further Swagger requirements/configuration see the Swagger spec

Using Swagger UI

Eventually the JSON file is fed into Swagger UI which provides a sandbox for using ONOS's REST API's:

 

 

The OnosSwaggerMojo can be used to generate Swagger compliant documentation for any REST API that applications on top of ONOS provide. 

 

  • No labels