opendaylight/md-sal/sal-rest-docgen/src/main/java/org/opendaylight/controller/sal/rest/doc/api/ApiDocService.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.controller.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
  20  * (See <a href="https://helloreverb.com/developers/swagger">https://helloreverb.com/developers/swagger</a>)
  21  * compliant documentation for RESTCONF APIs. The output of this is used by embedded Swagger UI.
  22  */
  23 @Path("/")
  24 public interface ApiDocService {
  25
  26   /**
  27    * Generates index document for Swagger UI. This document lists out all modules with link to get APIs for
  28    * each module. The API for each module is served by <code> getDocByModule()</code> method.
  29    *
  30    * @param uriInfo
  31    * @return
  32    */
  33   @GET
  34   @Produces(MediaType.APPLICATION_JSON)
  35   public Response getRootDoc(@Context javax.ws.rs.core.UriInfo uriInfo);
  36
  37   /**
  38    * Generates Swagger compliant document listing APIs for module.
  39    *
  40    * @param module
  41    * @param revision
  42    * @param uriInfo
  43    * @return
  44    */
  45   @GET
  46   @Path("/{module},{revision}")
  47   @Produces(MediaType.APPLICATION_JSON)
  48   public Response getDocByModule(@PathParam("module") String module,
  49                                  @PathParam("revision") String revision,
  50                                  @Context javax.ws.rs.core.UriInfo uriInfo);
  51
  52   /**
  53    * Redirects to embedded swagger ui.
  54    *
  55    * @param uriInfo
  56    * @return
  57    */
  58   @GET
  59   @Path("/ui")
  60   @Produces(MediaType.TEXT_HTML)
  61   public Response getApiExplorer(@Context javax.ws.rs.core.UriInfo uriInfo);
  62 }