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 (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 ApiDocService {
  26
  27     /**
  28      * Generates index document for Swagger UI. This document lists out all
  29      * modules with link to get APIs for each module. The API for each module is
  30      * served by <code> getDocByModule()</code> method.
  31      *
  32      * @param uriInfo
  33      * @return
  34      */
  35     @GET
  36     @Produces(MediaType.APPLICATION_JSON)
  37     public Response getRootDoc(@Context javax.ws.rs.core.UriInfo uriInfo);
  38
  39     /**
  40      * Generates Swagger compliant document listing APIs for module.
  41      *
  42      * @param module
  43      * @param revision
  44      * @param uriInfo
  45      * @return
  46      */
  47     @GET
  48     @Path("/{module}({revision})")
  49     @Produces(MediaType.APPLICATION_JSON)
  50     public Response getDocByModule(@PathParam("module") String module,
  51             @PathParam("revision") String revision, @Context javax.ws.rs.core.UriInfo uriInfo);
  52
  53     /**
  54      * Redirects to embedded swagger ui.
  55      *
  56      * @param uriInfo
  57      * @return
  58      */
  59     @GET
  60     @Path("/ui")
  61     @Produces(MediaType.TEXT_HTML)
  62     public Response getApiExplorer(@Context javax.ws.rs.core.UriInfo uriInfo);
  63
  64     /**
  65      * Generates index document for Swagger UI. This document lists out all
  66      * modules with link to get APIs for each module. The API for each module is
  67      * served by <code> getDocByModule()</code> method.
  68      *
  69      * @param uriInfo
  70      * @return
  71      */
  72     @GET
  73     @Path("/mounts")
  74     @Produces(MediaType.APPLICATION_JSON)
  75     public Response getListOfMounts(@Context javax.ws.rs.core.UriInfo uriInfo);
  76
  77     @GET
  78     @Path("/mounts/{instance}")
  79     @Produces(MediaType.APPLICATION_JSON)
  80     public Response getMountRootDoc(@PathParam("instance") String instanceNum,
  81             @Context javax.ws.rs.core.UriInfo uriInfo);
  82
  83     /**
  84      * Generates Swagger compliant document listing APIs for module.
  85      *
  86      * @param module
  87      * @param revision
  88      * @param uriInfo
  89      * @return
  90      */
  91     @GET
  92     @Path("/mounts/{instance}/{module}({revision})")
  93     @Produces(MediaType.APPLICATION_JSON)
  94     public Response getMountDocByModule(@PathParam("instance") String instanceNum,
  95             @PathParam("module") String module, @PathParam("revision") String revision,
  96             @Context javax.ws.rs.core.UriInfo uriInfo);
  97
  98 }