Add documentation for Read the docs

This patch adds basic documentation for Read the Docs generaiton.

Change-Id: Iceea0034de1488ed07c8623adab520dd149468a3
Issue-ID: MUSIC-62
Signed-off-by: Shashank Kumar Shankar <shashank.kumar.shankar@intel.com>

diff --git a/README.rst b/README.rst
deleted file mode 100644 (file)
index ac3b1f9..0000000
--- a/README.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-Distributed Key Value Store using Consul to store application configuration data.
-
-# TODO (Add documentation on how to run)
-
-# Sample Curl examples:
-
-## Load default configuration
-`curl -X GET localhost:8080/v1/config/load-default`
-
-## Register new domain
-`curl -X POST -d '{"domain":"<project>"}' localhost:8080/v1/register`
-`export TOKEN=`
-## Register new sub domain 
-`curl -X POST -d '{"subdomain":"<sub-project>"}' localhost:8080/v1/register/$TOKEN/subdomain`
-
-## Check if a domain is already registered.
-`curl -X GET localhost:8080/v1/register/$TOKEN`
-
-## List all sub domains in a domain.
-`TODO`
-
-## Upload properties file to domain or subdomain.
-`curl -X POST -F 'token=$TOKEN' -F 'configFile=@./example.properties' localhost:8080/v1/config`
-`curl -X POST -F 'token=$TOKEN' -F 'subdomain=<sub-domain>' -F 'configFile=@./example.properties' localhost:8080/v1/config`
-
-## Load properties file into Consul
-`curl -X POST -d '{"token":"$TOKEN", "filename": "example.properties"}' localhost:8080/v1/config/load`
-
-## Fetch properties file
-`curl -X GET localhost:8080/v1/config/$TOKEN/example.properties`
-`curl -X GET localhost:8080/v1/config/$TOKEN/<sub-domain>/example.properties`
-
-## Delete properties file
-`curl -X DELETE localhost:8080/v1/config/$TOKEN/example.properties`
-`curl -X DELETE localhost:8080/v1/config/$TOKEN/<sub-domain>/example.properties`
-
-## Delete project/sub project
-`curl -X DELETE localhost:8080/v1/register/$TOKEN/subdomain/<sub-domain>`
-`curl -X DELETE localhost:8080/v1/register/$TOKEN`

diff --git a/docs/commandsamples.rst b/docs/commandsamples.rst
new file mode 100644 (file)
index 0000000..5ac5a0d
--- /dev/null
+++ b/docs/commandsamples.rst
@@ -0,0 +1,46 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Sample Commands
+===============
+
+.. code-block:: console
+
+    ## Load default configuration
+    curl -X GET localhost:8080/v1/config/load-default
+
+    ## Check if Keys were loaded into Consul
+    curl -X GET localhost:8080/v1/getconfigs
+
+    ## Check value for a single key
+    curl -X GET localhost:8080/v1/getconfig/<key>
+
+    ## Register new domain
+    curl -X POST -d '{"domain":"new_project"}' localhost:8080/v1/register
+    export TOKEN=
+    ## Register new sub domain
+    curl -X POST -d '{"subdomain":"sub_project"}' localhost:8080/v1/register/$TOKEN/subdomain
+
+    ## Check if a domain is already registered.
+    curl -X GET localhost:8080/v1/register/$TOKEN
+
+    ## Upload properties file to domain or subdomain.
+    curl -X POST -F 'token=$TOKEN' -F 'configFile=@./example.properties' localhost:8080/v1/config
+    curl -X POST -F 'token=$TOKEN' -F 'subdomain=sub_domain' -F 'configFile=@./example.properties' localhost:8080/v1/config
+
+    ## Load properties file into Consul
+    curl -X POST -d '{"token":"$TOKEN", "filename": "example.properties"}' localhost:8080/v1/config/load
+
+    ## Fetch properties file
+    curl -X GET localhost:8080/v1/config/$TOKEN/example.properties
+    curl -X GET localhost:8080/v1/config/$TOKEN/sub_domain/example.properties
+
+    ## Delete properties file
+    curl -X DELETE localhost:8080/v1/config/$TOKEN/example.properties
+    curl -X DELETE localhost:8080/v1/config/$TOKEN/sub_domain/example.properties
+
+    ## Delete project/sub project
+    curl -X DELETE localhost:8080/v1/register/$TOKEN/sub_domain/sub-domain
+    curl -X DELETE localhost:8080/v1/register/$TOKEN
+
+.. end

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644 (file)
index 0000000..86eb231
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,13 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Distributed KV store Documentation
+==================================
+
+.. toctree::
+   :maxdepth: 1
+
+    index
+    installation
+    offeredapis
+    commandsamples

diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644 (file)
index 0000000..24fa5c4
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,32 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Installation
+============
+
+As for current release, project is packaged as a single Docker Container. For subsequent
+releases, it will be integrated with OOM.
+
+.. code-block:: console
+
+    # Set Datastore as Consul
+    DATASTORE="consul"
+    # Set IP address of where Consul is running
+    DATASTORE_IP="localhost"
+    # Set mountpath inside the container where persistent data is stored.
+    MOUNTPATH="/dkv_mount_path/configs/"
+    # Place all Config data which needs to be loaded in default directory.
+    DEFAULT_CONFIGS=$(pwd)/mountpath/default
+    # Create the directories.
+    mkdir -p mountpath/default
+    # Login to Nexus.
+    docker login -u docker -p docker nexus3.onap.org:10001
+    # Pull distributed-kv-store image.
+    docker pull nexus3.onap.org:10001/onap/music/distributed-kv-store
+    # Run the distributed-kv-store image.
+    docker run -e DATASTORE=$DATASTORE -e DATASTORE_IP=$DATASTORE_IP -e MOUNTPATH=$MOUNTPATH -d \
+           --name dkv \
+           -v $DEFAULT_CONFIGS:/dkv_mount_path/configs/default \
+           -p 8200:8200 -p 8080:8080 nexus3.onap.org:10001/onap/music/distributed-kv-store
+
+.. end

diff --git a/docs/offeredapis.rst b/docs/offeredapis.rst
new file mode 100644 (file)
index 0000000..01de50f
--- /dev/null
+++ b/docs/offeredapis.rst
@@ -0,0 +1,7 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Offered APIs
+============
+
+.. swaggerv2doc:: swagger.yaml

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
new file mode 100644 (file)
index 0000000..9b3de2a
--- /dev/null
+++ b/docs/swagger.yaml
@@ -0,0 +1,428 @@
+swagger: '2.0'
+info:
+  description: API reference for Distributed Key Value store.
+  version: 1.0.0
+  title: API reference for Distributed Key Value store
+  contact:
+    email: shashank.kumar.shankar@intel.com
+    url: 'https://wiki.onap.org/pages/viewpage.action?pageId=16010913'
+  license:
+    name: Apache 2.0
+    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+basePath: /v1
+schemes:
+  - http
+paths:
+  /register:
+    post:
+      tags:
+        - Domain
+      summary: Endpoint to Register new domain
+      description: ''
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - in: body
+          name: body
+          description: Register new domain.
+          required: true
+          schema:
+            $ref: '#/definitions/RegisterDomainPOSTRequest'
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/RegisterDomainPOSTResponse'
+  '/register/{token}':
+    get:
+      tags:
+        - Domain
+      summary: Check if domain is registered.
+      description: Check if domain is registered identified by token.
+      produces:
+        - application/json
+      parameters:
+        - name: token
+          in: path
+          description: Token used to query
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/RegisterDomainGETResponse'
+    delete:
+      tags:
+        - Domain
+      summary: Delete registered domain.
+      description: Deletes a registered domain identified by token.
+      produces:
+        - application/json
+      parameters:
+        - name: token
+          in: path
+          description: Token used to delete
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/RegisterDomainDELETEResponse'
+  '/register/{token}/subdomain':
+    post:
+      tags:
+        - Subdomain
+      summary: Endpoint to Register new subdomain
+      description: ''
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - name: token
+          in: path
+          description: Token used to identify domain.
+          required: true
+          type: string
+        - in: body
+          name: body
+          description: Register new subdomain.
+          required: true
+          schema:
+            $ref: '#/definitions/RegisterSubdomainPOSTRequest'
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/RegisterSubdomainPOSTResponse'
+  '/register/{token}/subdomain/{subdomain}':
+    delete:
+      tags:
+        - Subdomain
+      summary: Delete registered subdomain.
+      description: Deletes a registered subdomain identified by token and subdomain.
+      produces:
+        - application/json
+      parameters:
+        - name: token
+          in: path
+          description: Token used to delete
+          required: true
+          type: string
+        - name: subdomain
+          in: path
+          description: Subdomain used to delete
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/RegisterSubDomainDELETEResponse'
+  /config:
+    post:
+      tags:
+        - Config
+      summary: Endpoint to upload configuration.
+      description: Endpoint to upload configuration.
+      consumes:
+        - multipart/form-data
+      produces:
+        - application/json
+      parameters:
+        - name: configFile
+          in: formData
+          description: Config file to be uploaded.
+          required: true
+          type: file
+        - name: token
+          in: formData
+          description: Token to identify domain to upload config file to.
+          required: true
+          type: string
+        - name: subdomain
+          in: formData
+          description: Subdomain to identify subdomain to upload config file to.
+          required: false
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConfigUploadResponse'
+  '/config/{token}/{filename}':
+    get:
+      tags:
+        - Config
+      summary: Get config file.
+      description: Get config file identified by token and filename.
+      produces:
+        - file
+      parameters:
+        - name: token
+          in: path
+          description: Token used to get config file.
+          required: true
+          type: string
+        - name: filename
+          in: path
+          description: Filename used to get config file.
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+    delete:
+      tags:
+        - Config
+      summary: Delete config file.
+      description: Deletes a config file identified by token and filename.
+      produces:
+        - application/json
+      parameters:
+        - name: token
+          in: path
+          description: Token used to delete
+          required: true
+          type: string
+        - name: filename
+          in: path
+          description: Filename used to delete
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConfigDomainDELETEResponse'
+  '/config/{token}/{subdomain}/{filename}':
+    get:
+      tags:
+        - Config
+      summary: Get config file from subdomain.
+      description: 'Get config file identified by token, filename and subdomain.'
+      produces:
+        - file
+      parameters:
+        - name: token
+          in: path
+          description: Token used to get config file.
+          required: true
+          type: string
+        - name: subdomain
+          in: path
+          description: Subdomain used to get config file.
+          required: true
+          type: string
+        - name: filename
+          in: path
+          description: Filename used to get config file.
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+    delete:
+      tags:
+        - Config
+      summary: Delete config file from subdomain.
+      description: 'Deletes a config file identified by token, filename and subdomain.'
+      produces:
+        - application/json
+      parameters:
+        - name: token
+          in: path
+          description: Token used to delete config file.
+          required: true
+          type: string
+        - name: subdomain
+          in: path
+          description: Subdomain used to delete config file.
+          required: true
+          type: string
+        - name: filename
+          in: path
+          description: Filename used to delete config file.
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConfigSubDomainDELETEResponse'
+  /config/load:
+    post:
+      tags:
+        - Config
+      summary: Load config into Consul.
+      description: Load config into Consul upon hitting the endpoint.
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - in: body
+          name: body
+          description: Load configuration from file system to be added into Consul
+          required: true
+          schema:
+            $ref: '#/definitions/ConfigLoadPOSTRequest'
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConfigLoadPOSTResponse'
+  /config/load-default:
+    get:
+      tags:
+        - Config
+      summary: Load default config into Consul.
+      description: Load default config into Consul upon hitting the endpoint.
+      produces:
+        - application/json
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConfigDefaultGETResponse'
+  /getconfigs:
+    get:
+      tags:
+        - Consul operation
+      summary: Get all keys present in Consul.
+      description: Returns a list of keys present in Consul.
+      produces:
+        - application/json
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConsulGETAllResponse'
+  '/getconfig/{key}':
+    get:
+      tags:
+        - Consul operation
+      summary: Get value for specific key present in Consul.
+      description: Returns a key and value present in Consul.
+      produces:
+        - application/json
+      parameters:
+        - name: key
+          in: path
+          description: Key used to query Consul.
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConsulGETResponse'
+  '/deleteconfig/{key}':
+    delete:
+      tags:
+        - Consul operation
+      summary: Delete value for specific key present in Consul.
+      description: Deletes a specific key.
+      produces:
+        - application/json
+      parameters:
+        - name: key
+          in: path
+          description: Key used to delete
+          required: true
+          type: string
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/ConsulDELETEResponse'
+definitions:
+  RegisterDomainPOSTRequest:
+    type: object
+    properties:
+      domain:
+        type: string
+  RegisterDomainPOSTResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  RegisterDomainGETResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  RegisterDomainDELETEResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  RegisterSubdomainPOSTRequest:
+    type: object
+    properties:
+      subdomain:
+        type: string
+  RegisterSubdomainPOSTResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  RegisterSubDomainDELETEResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConfigUploadResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConfigDomainDELETEResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConfigSubDomainDELETEResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConfigLoadPOSTRequest:
+    type: object
+    properties:
+      token:
+        type: string
+      filename:
+        type: string
+      subdomain:
+        type: string
+  ConfigLoadPOSTResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConfigDefaultGETResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConsulGETAllResponse:
+    type: object
+    properties:
+      response:
+        items:
+          type: string
+  ConsulGETResponse:
+    type: object
+    properties:
+      response:
+        type: string
+  ConsulDELETEResponse:
+    type: object
+    properties:
+      response:
+        type: string