From 77ea4c747782cc753e33b9b7bee3adb5d92a232c Mon Sep 17 00:00:00 2001 From: Victor Morales Date: Mon, 20 Aug 2018 08:17:35 -0700 Subject: Fix swaggerv2doc sphinx extension This change fixes the error caused for missing sphinxcontrib-swaggerdoc python module. It also adds the rstcheck python module to prevent future errors. Change-Id: I9db569e8bd5045d2239c1dadb1ac912ce8ee3db9 Issue-ID: DOC-300 Signed-off-by: Victor Morales --- .gitignore | 4 +- .rstcheck.cfg | 2 + docs/conf.py | 41 ++++ docs/index.rst | 7 +- docs/offeredapis.rst | 2 +- docs/swagger.json | 653 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/swagger.yaml | 428 --------------------------------- tox.ini | 21 ++ 8 files changed, 724 insertions(+), 434 deletions(-) create mode 100644 .rstcheck.cfg create mode 100644 docs/conf.py create mode 100644 docs/swagger.json delete mode 100644 docs/swagger.yaml create mode 100644 tox.ini diff --git a/.gitignore b/.gitignore index 155fd31..124e2b7 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,6 @@ pkg/ target/ src/github.com/ .vscode -src/golang.org/ \ No newline at end of file +src/golang.org/ +.tox/ +docs/build/ diff --git a/.rstcheck.cfg b/.rstcheck.cfg new file mode 100644 index 0000000..2c5eae6 --- /dev/null +++ b/.rstcheck.cfg @@ -0,0 +1,2 @@ +[rstcheck] +ignore_directives=swaggerv2doc diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..4a33734 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,41 @@ +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +BASE_DIR = os.path.dirname(os.path.abspath(__file__)) +ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) + +sys.path.insert(0, ROOT) +sys.path.insert(0, BASE_DIR) + +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinxcontrib.swaggerdoc', + #'sphinx.ext.intersphinx' +] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Distributed Key-Value store' diff --git a/docs/index.rst b/docs/index.rst index 86eb231..e12302b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,6 @@ Distributed KV store Documentation .. toctree:: :maxdepth: 1 - index - installation - offeredapis - commandsamples + Installation + Offered APIs + Command Samples diff --git a/docs/offeredapis.rst b/docs/offeredapis.rst index 01de50f..a2129f3 100644 --- a/docs/offeredapis.rst +++ b/docs/offeredapis.rst @@ -4,4 +4,4 @@ Offered APIs ============ -.. swaggerv2doc:: swagger.yaml +.. swaggerv2doc:: swagger.json diff --git a/docs/swagger.json b/docs/swagger.json new file mode 100644 index 0000000..2a7e656 --- /dev/null +++ b/docs/swagger.json @@ -0,0 +1,653 @@ +{ + "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" + } + } + } + } +} \ No newline at end of file diff --git a/docs/swagger.yaml b/docs/swagger.yaml deleted file mode 100644 index 9b3de2a..0000000 --- a/docs/swagger.yaml +++ /dev/null @@ -1,428 +0,0 @@ -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 diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..8cc5d8a --- /dev/null +++ b/tox.ini @@ -0,0 +1,21 @@ +[tox] +minversion = 1.6 +skipsdist = True +envlist = rstcheck + +[testenv] +passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY +usedevelop = False +install_command = pip install {opts} {packages} + +[testenv:rstcheck] +deps = rstcheck +whitelist_externals = bash +commands = bash -c "find {toxinidir} -not -path {toxinidir}/.tox/\* \ + -name \*.rst -type f -print0 | xargs -0 rstcheck" + +[testenv:docs] +deps = + sphinx + sphinxcontrib-swaggerdoc +commands = sphinx-build -W -b html docs docs/build/html -- cgit 1.2.3-korg