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