restconf/sal-rest-docgen/src/main/java/org/opendaylight/netconf/sal/rest/doc/api/OpenApiService.java

   1 /*
   2  * Copyright (c) 2014 Cisco 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.api;
   9
  10 import javax.ws.rs.GET;
  11 import javax.ws.rs.Path;
  12 import javax.ws.rs.PathParam;
  13 import javax.ws.rs.Produces;
  14 import javax.ws.rs.core.Context;
  15 import javax.ws.rs.core.MediaType;
  16 import javax.ws.rs.core.Response;
  17
  18 /**
  19  * This service generates swagger (See <a
  20  * href="https://helloreverb.com/developers/swagger"
  21  * >https://helloreverb.com/developers/swagger</a>) compliant documentation for
  22  * RESTCONF APIs. The output of this is used by embedded Swagger UI.
  23  */
  24 @Path("/")
  25 public interface OpenApiService {
  26
  27     @GET
  28     @Path("/single")
  29     @Produces(MediaType.APPLICATION_JSON)
  30     Response getAllModulesDoc(@Context javax.ws.rs.core.UriInfo uriInfo);
  31
  32     /**
  33      * Generates Swagger compliant document listing APIs for module.
  34      */
  35     @GET
  36     @Path("/{module}({revision})")
  37     @Produces(MediaType.APPLICATION_JSON)
  38     Response getDocByModule(@PathParam("module") String module,
  39                             @PathParam("revision") String revision, @Context javax.ws.rs.core.UriInfo uriInfo);
  40
  41     /**
  42      * Redirects to embedded swagger ui.
  43      */
  44     @GET
  45     @Path("/ui")
  46     @Produces(MediaType.TEXT_HTML)
  47     Response getApiExplorer(@Context javax.ws.rs.core.UriInfo uriInfo);
  48
  49     /**
  50      * Generates index document for Swagger UI. This document lists out all
  51      * modules with link to get APIs for each module. The API for each module is
  52      * served by <code> getDocByModule()</code> method.
  53      */
  54     @GET
  55     @Path("/mounts")
  56     @Produces(MediaType.APPLICATION_JSON)
  57     Response getListOfMounts(@Context javax.ws.rs.core.UriInfo uriInfo);
  58
  59     /**
  60      * Generates Swagger compliant document listing APIs for module.
  61      */
  62     @GET
  63     @Path("/mounts/{instance}/{module}({revision})")
  64     @Produces(MediaType.APPLICATION_JSON)
  65     Response getMountDocByModule(@PathParam("instance") String instanceNum,
  66                                  @PathParam("module") String module, @PathParam("revision") String revision,
  67                                  @Context javax.ws.rs.core.UriInfo uriInfo);
  68
  69     /**
  70      * Generates Swagger compliant document listing APIs for all modules of mount point.
  71      */
  72     @GET
  73     @Path("/mounts/{instance}")
  74     @Produces(MediaType.APPLICATION_JSON)
  75     Response getMountDoc(@PathParam("instance") String instanceNum,
  76                          @Context javax.ws.rs.core.UriInfo uriInfo);
  77
  78 }