From: Samuel Schneider <samuel.schneider@pantheon.tech>
Date: Mon, 16 Oct 2023 17:16:05 +0000 (+0200)
Subject: OpenApi: Document feature installation and usage
X-Git-Tag: v7.0.0~342
X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;ds=sidebyside;h=fa9e8fa7c788765170333941a57cea4a5c8e0807;p=netconf.git

OpenApi: Document feature installation and usage

Add dedicated paragraph into Netconf user guide which
document OpenApi feature installation and usage.

JIRA: NETCONF-1181
Change-Id: I46facaea023f9b981b12089448139affd336d7b2
Signed-off-by: Samuel Schneider <samuel.schneider@pantheon.tech>
Signed-off-by: Ivan Hrasko <ivan.hrasko@pantheon.tech>
---

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 34d1611b5d..8767781d58 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -53,6 +53,8 @@ the device.**
     NETCONF southbound can be activated by installing
     ``odl-netconf-connector-all`` Karaf feature.
 
+.. _netconf-connector:
+
 Netconf-connector configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2032,3 +2034,65 @@ RESTCONF response:
             ]
         }
     }
+
+RESTCONF OpenAPI
+----------------
+
+Overview
+~~~~~~~~
+
+The OpenAPI provides full API for configurational data which can be edited (by POST, PUT, PATCH and DELETE).
+For operational data we only provide GET API. For the majority of requests 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 an
+example is when data are representing an operational (config false) container with no config data in it.
+
+
+Using the OpenAPI Explorer through HTTP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Install OpenApi into Karaf by installing karaf feature:
+
+::
+
+    $ feature:install odl-restconf-openapi
+
+2.  Navigate to OpenAPI in your web browser which is available at URLs:
+
+-  http://localhost:8181/openapi/explorer/index.html for general overview
+
+-  http://localhost:8181/openapi/api/v3/single for JSON data
+
+.. note::
+
+    In the URL links for OpenAPI, change *localhost* to the IP/Host name of your actual server.
+
+3.  Enter the username and password.
+    By default the credentials are  *admin/admin*.
+
+4.  Select any model to try out.
+
+5.  Select any available request to try out.
+
+6.  Click on the **Try it out** button.
+
+7.  Provide any required parameters or edit request body.
+
+8.  Click the **Execute** button.
+
+9.  You can see responses to the given request.
+
+
+OpenAPI Explorer ca be used for connected device too. How to connect device can be found :ref:`here <netconf-connector>`.
+
+OpenAPI URLs in that case would look like this:
+
+-  `http://localhost:8181/openapi/explorer/index.html?urls.primaryName=17830-sim-device resources - RestConf RFC 8040 <http://localhost:8181/openapi/explorer/index.html?urls.primaryName=17830-sim-device%20resources%20-%20RestConf%20RFC%208040>`_ for device overview
+
+-  http://localhost:8181/openapi/api/v3/mounts/1 for JSON data
+
+-  `http://localhost:8181/openapi/api/v3/mounts/1/toaster(2009-11-20) <http://localhost:8181/openapi/api/v3/mounts/1/toaster(2009-11-20)>`__ JSON data for given model
+
+.. note::
+
+    The URL links for OpenAPI are made for device with name *17830-sim-device* and model toaster
+    with *2009-11-20* revision and need to be changed accordingly to connected device.