restconf/sal-rest-docgen/src/main/java/org/opendaylight/netconf/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.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 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     @GET
  33     @Produces(MediaType.APPLICATION_JSON)
  34     Response getRootDoc(@Context javax.ws.rs.core.UriInfo uriInfo);
  35
  36     /**
  37      * Generates Swagger compliant document listing APIs for module.
  38      */
  39     @GET
  40     @Path("/{module}({revision})")
  41     @Produces(MediaType.APPLICATION_JSON)
  42     Response getDocByModule(@PathParam("module") String module,
  43             @PathParam("revision") String revision, @Context javax.ws.rs.core.UriInfo uriInfo);
  44
  45     /**
  46      * Redirects to embedded swagger ui.
  47      */
  48     @GET
  49     @Path("/ui")
  50     @Produces(MediaType.TEXT_HTML)
  51     Response getApiExplorer(@Context javax.ws.rs.core.UriInfo uriInfo);
  52
  53     /**
  54      * Generates index document for Swagger UI. This document lists out all
  55      * modules with link to get APIs for each module. The API for each module is
  56      * served by <code> getDocByModule()</code> method.
  57      */
  58     @GET
  59     @Path("/mounts")
  60     @Produces(MediaType.APPLICATION_JSON)
  61     Response getListOfMounts(@Context javax.ws.rs.core.UriInfo uriInfo);
  62
  63     @GET
  64     @Path("/mounts/{instance}")
  65     @Produces(MediaType.APPLICATION_JSON)
  66     Response getMountRootDoc(@PathParam("instance") String instanceNum,
  67             @Context javax.ws.rs.core.UriInfo uriInfo);
  68
  69     /**
  70      * Generates Swagger compliant document listing APIs for module.
  71      */
  72     @GET
  73     @Path("/mounts/{instance}/{module}({revision})")
  74     @Produces(MediaType.APPLICATION_JSON)
  75     Response getMountDocByModule(@PathParam("instance") String instanceNum,
  76             @PathParam("module") String module, @PathParam("revision") String revision,
  77             @Context javax.ws.rs.core.UriInfo uriInfo);
  78
  79 }