diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.rst | 50 |
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. |