information-coordinator-service/src/main/java/org/oransc/ics/SwaggerConfig.java

   1 /*-
   2  * ========================LICENSE_START=================================
   3  * O-RAN-SC
   4  * %%
   5  * Copyright (C) 2019 Nordix Foundation
   6  * %%
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  * ========================LICENSE_END===================================
  19  */
  20
  21 package org.oransc.ics;
  22
  23 import io.swagger.v3.oas.annotations.OpenAPIDefinition;
  24 import io.swagger.v3.oas.annotations.info.Info;
  25 import io.swagger.v3.oas.annotations.info.License;
  26
  27 /**
  28  * Swagger configuration class that uses swagger documentation type and scans
  29  * all the controllers. To access the swagger gui go to
  30  * http://ip:port/swagger-ui.html
  31  */
  32
  33 @OpenAPIDefinition( //
  34     info = @Info(
  35         title = SwaggerConfig.API_TITLE, //
  36         version = "1.0", //
  37         description = SwaggerConfig.DESCRIPTION, //
  38         license = @License(
  39             name = "Copyright (C) 2020-2022 Nordix Foundation. Licensed under the Apache License.",
  40             url = "http://www.apache.org/licenses/LICENSE-2.0")))
  41 public class SwaggerConfig {
  42     private SwaggerConfig() {
  43     }
  44
  45     static final String API_TITLE = "Data management and exposure";
  46
  47     static final String DESCRIPTION = "<h1>API documentation</h1>" //
  48         + "<h2>General</h2>" //
  49         + "<p>" //
  50         + "  The ICS is a data subscription service which decouples data producers from data consumers."
  51         + "  A data consumer can create a data subscription (Information Job) without any knowledge of its data producers (one subscription may involve several data producers)."
  52         + "  A data producer has the ability to produce one or several types of data (Information Type)."
  53         + "  One type of data can be produced by zero to many producers." + "  <br /><br />"
  54         + "  A data consumer can have several active data subscriptions (Information Job)."
  55         + "  One Information Job consists of the type of data to produce and additional parameters, which may be different for different data types." //
  56         + "  These parameters are not defined or limited by this service and may for instance include:" + "  <ul>" //
  57         + "   <li>Parameters related to delivery (Kafka stream, callback URL etc.). These are different for different delivery protocols.</li>"
  58         + "   <li>Filtering information (scope, filter or other discriminators).</li>" + "   <li>Periodicy</li>"
  59         + "   <li>Other info used for aggregation</li>" + "   <ul>" //
  60         + "</p>" //
  61         + "<h2>APIs provided by the service</h2>" //
  62         + "<h4>A1-EI</h4>" //
  63         + "<p>" //
  64         + "  This API is between Near-RT RIC and the Non-RT RIC." //
  65         + "  The Near-RT RIC is a data consumer, which creates Information Jobs to subscribe for data." //
  66         + "  In this context, the information is referred to as 'Enrichment Information', EI." //
  67         + "</p>" //
  68         + "<h4>Data producer API</h4>" //
  69         + "<p>" //
  70         + "  This API is provided by the Non-RT RIC platform and is intended to be part of the O-RAN R1 interface." //
  71         + "  The API is for use by different kinds of data producers and provides support for:" //
  72         + "<ul>" //
  73         + "<li>Registry of supported information types and which parameters needed to setup a subscription.</li>" //
  74         + "<li>Registry of existing data producers.</li>" //
  75         + "<li>Callback API provided by producers to setup subscriptions.</li>" //
  76         + "</ul>" //
  77         + "</p>" //
  78         + "<h4>Data consumer API</h4>" //
  79         + "<p>" //
  80         + "  This API is provided by the Non-RT RIC platform and is intended to be part of the O-RAN R1 interface." //
  81         + "  The API is for use by different kinds of data consumers and provides support for:" //
  82         + "<ul>" //
  83         + "<li>Querying of available types of data to consume.</li>" //
  84         + "<li>Management of data subscription jobs</li>" //
  85         + "<li>Optional callback API provided by consumers to get notification on added and removed information types.</li>" //
  86         + "</ul>" //
  87         + "</p>" //
  88         + "<h4>Service status</h4>" //
  89         + "<p>" //
  90         + "  This API provides a means to monitor the health of this service." //
  91         + "</p>";
  92
  93 }