summaryrefslogtreecommitdiffstats
path: root/docs/index.rst
diff options
context:
space:
mode:
authorHuabingZhao <zhao.huabing@zte.com.cn>2017-10-23 05:48:03 +0000
committerGerrit Code Review <gerrit@onap.org>2017-10-23 05:48:03 +0000
commit68907a497cbf509c94f667a0707d11c30ef2611a (patch)
tree200ffdca31bf75ae90f07c43148a6a1e5ff6e749 /docs/index.rst
parent9fe93f3958bcc4f44bc84d65ab9eb4e43859afcc (diff)
parent97a960aae39c68ec7f41d2b9c2e97ebc6158e5da (diff)
Merge "Add swagger sdk docs"
Diffstat (limited to 'docs/index.rst')
-rw-r--r--docs/index.rst50
1 files changed, 46 insertions, 4 deletions
diff --git a/docs/index.rst b/docs/index.rst
index 833e1aa..5a72d0a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,50 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 Huawei Technologies Co., Ltd.
-TODO Add files to toctree and delete this header
-------------------------------------------------
-.. toctree::
- :maxdepth: 1
+.. _swagger_sdk:
+
+Swagger SDK
+===========
+
+Swagger
+--------
+Swagger helps on following aspects:
+
+* Define REST API based on OAS standard, as swagger.json
+* Auto generate the REST service code, using swagger.json with swagger annotations.
+* Auto generate the client sdk code, using swagger.json in different language
+* Provides readable REST API document using swagger.json
+
+And for implementing mirco-services, swagger is being an default technology.
+
+Problems in mirco-services development
+--------------------------------------
+
+Following problem occurs in micro-service based products as there is no process exist to govern them:
+
+* Most of the time, developers manually authors the swagger REST API document, and it leads to inconsistent between the actual REST API implementation and API defined the document.
+* For mirco-services, developer starts to write the client sdk manually and which will also brings inconsistent between actual REST API provided by mirco-service and the client SDK implementation.
+* Client SDK in different languages become an huge effort involved and most of time, teams do not provide the client SDK in required languages of different micro-service, dependenting on another micro-service.
+* When depending services (B) changes the REST API, its only detected at system testing and integration testing phase of dependent service (A). Because client SDK of B is implemented by service A team, because service A does not provide the client SDK in required language as mentioned above.
+
+To address these problems, Swagger-SDK is brought into ONAP, as ONAP is mirco-service based architecture.
+
+What does Swagger-SDK provide:
+------------------------------
+It provides feature in build-time and run-time.
+
+Build-time feature
+------------------
+
+* Generate the java client SDK for those services, which provides swagger.json already and deploy it in nexus in following package ::
+
+ [ Project Maven Group-id] ::[ Project maven artifact-id]-java-sdk :: [project maven version]
+
+* Generate the swagger.json for those services, which is already annotated with swagger java annotations. Also it deploy it in nexus in following package ::
+
+ [ Project Maven Group-id] ::[ Project maven artifact-id]-swagger-schema :: [project maven version]
+
+MSB is already supported with this feature.