Add global description

Add global description (info/description) to OpenApi that
states that we are providing full API for configurational
data because only those can be edited (by POST, PUT, PATCH,
DELETE) and for operational we only provide GET API.

In addition, for majority of request user can see only
config data in examples. That’s because we can show only one
example per request.

The exception when user can see operational data in example
is when data are representing operational (config false)
container with no config data in it.

JIRA: NETCONF-1138
Change-Id: I5c9de0c8780289f4557c7ce9995b8cb5d44e0290
Signed-off-by: lubos-cicut <lubos.cicut@pantheon.tech>

diff --git a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/impl/BaseYangOpenApiGenerator.java b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/impl/BaseYangOpenApiGenerator.java
index c27ffa432bfb70b74f503feab9ba8fa9efae8092..e004cb5ff855fca83a7a5047e722dbef0c672810 100644 (file)
--- a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/impl/BaseYangOpenApiGenerator.java
+++ b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/impl/BaseYangOpenApiGenerator.java
@@ -71,6 +71,12 @@ public abstract class BaseYangOpenApiGenerator {
     public static final String BASIC_AUTH_NAME = "basicAuth";
     public static final Http OPEN_API_BASIC_AUTH = new Http("basic", null, null);
     public static final List<Map<String, List<String>>> SECURITY = List.of(Map.of(BASIC_AUTH_NAME, List.of()));
+    public static final String DESCRIPTION = """
+        We are providing full API for configurational data which can be edited (by POST, PUT, PATCH and DELETE).
+        For operational data we only provide GET API.\n
+        For majority of request you can see only config data in examples. That’s because we can show only one example
+        per request. The exception when you can see operational data in example is when data are representing
+        operational (config false) container with no config data in it.""";
 
     private final DOMSchemaService schemaService;
 
@@ -83,7 +89,7 @@ public abstract class BaseYangOpenApiGenerator {
         final var schema = createSchemaFromUriInfo(uriInfo);
         final var host = createHostFromUriInfo(uriInfo);
         final var title = "Controller modules of RESTCONF";
-        final var info = new Info(API_VERSION, title);
+        final var info = new Info(API_VERSION, title, DESCRIPTION);
         final var servers = List.of(new Server(schema + "://" + host + BASE_PATH));
 
         final var paths = new HashMap<String, Path>();
@@ -148,7 +154,7 @@ public abstract class BaseYangOpenApiGenerator {
 
         final var schema = createSchemaFromUriInfo(uriInfo);
         final var host = createHostFromUriInfo(uriInfo);
-        final var info = new Info(API_VERSION, module.getName());
+        final var info = new Info(API_VERSION, module.getName(), DESCRIPTION);
         final var servers = List.of(new Server(schema + "://" + host + BASE_PATH));
         final var definitionNames = new DefinitionNames();
         final var schemas = getSchemas(module, schemaContext, definitionNames, true);

diff --git a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/Info.java b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/Info.java
index 1f452252efe64c8e8ebebd5b1ba6587cd59c6703..329c2e9f2dbfe3b442c986b4a72b8ac5960af5c6 100644 (file)
--- a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/Info.java
+++ b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/Info.java
@@ -12,11 +12,13 @@ import static java.util.Objects.requireNonNull;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
 
 @JsonInclude(Include.NON_NULL)
 public record Info(
         @NonNull String version,
-        @NonNull String title) {
+        @NonNull String title,
+        @Nullable String description) {
 
     public Info {
         requireNonNull(version);

diff --git a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/mountpoints/MountPointOpenApi.java b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/mountpoints/MountPointOpenApi.java
index d142bd7df12337a43c9d0d0e91eb65073990d984..a377408204cf5dd75138ecd9252887cbf7b200d8 100644 (file)
--- a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/mountpoints/MountPointOpenApi.java
+++ b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/mountpoints/MountPointOpenApi.java
@@ -12,6 +12,7 @@ import static java.util.Objects.requireNonNull;
 import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.API_VERSION;
 import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.BASE_PATH;
 import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.BASIC_AUTH_NAME;
+import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.DESCRIPTION;
 import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.OPEN_API_BASIC_AUTH;
 import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.OPEN_API_VERSION;
 import static org.opendaylight.restconf.openapi.impl.BaseYangOpenApiGenerator.SECURITY;
@@ -206,7 +207,7 @@ public class MountPointOpenApi implements DOMMountPointListener, AutoCloseable {
         final var schema = openApiGenerator.createSchemaFromUriInfo(uriInfo);
         final var host = openApiGenerator.createHostFromUriInfo(uriInfo);
         final var title = deviceName + " modules of RESTCONF";
-        final var info = new Info(API_VERSION, title);
+        final var info = new Info(API_VERSION, title, DESCRIPTION);
         final var servers = List.of(new Server(schema + "://" + host + BASE_PATH));
 
         final var modules = getSortedModules(context);
@@ -232,7 +233,7 @@ public class MountPointOpenApi implements DOMMountPointListener, AutoCloseable {
 
     private OpenApiObject generateDataStoreOpenApi(final UriInfo uriInfo, final String context,
             final String deviceName) {
-        final var info = new Info(API_VERSION, context);
+        final var info = new Info(API_VERSION, context, DESCRIPTION);
         final var schema = openApiGenerator.createSchemaFromUriInfo(uriInfo);
         final var host = openApiGenerator.createHostFromUriInfo(uriInfo);
         final var servers = List.of(new Server(schema + "://" + host + BASE_PATH));