From 9434f17d531a418a4314436e315c074fc8573135 Mon Sep 17 00:00:00 2001 From: Shashank Kumar Shankar Date: Wed, 28 Mar 2018 11:04:06 -0700 Subject: 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 --- README.rst | 39 ----- docs/commandsamples.rst | 46 ++++++ docs/index.rst | 13 ++ docs/installation.rst | 32 ++++ docs/offeredapis.rst | 7 + docs/swagger.yaml | 428 ++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 526 insertions(+), 39 deletions(-) delete mode 100644 README.rst create mode 100644 docs/commandsamples.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/offeredapis.rst create mode 100644 docs/swagger.yaml diff --git a/README.rst b/README.rst deleted file mode 100644 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":""}' localhost:8080/v1/register` -`export TOKEN=` -## Register new sub domain -`curl -X POST -d '{"subdomain":""}' 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=' -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//example.properties` - -## Delete properties file -`curl -X DELETE localhost:8080/v1/config/$TOKEN/example.properties` -`curl -X DELETE localhost:8080/v1/config/$TOKEN//example.properties` - -## Delete project/sub project -`curl -X DELETE localhost:8080/v1/register/$TOKEN/subdomain/` -`curl -X DELETE localhost:8080/v1/register/$TOKEN` diff --git a/docs/commandsamples.rst b/docs/commandsamples.rst new file mode 100644 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/ + + ## 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 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 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 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 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 -- cgit 1.2.3-korg