cps-ncmp-rest/docs/openapi/components.yaml

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2022 Nordix Foundation
   3 #  Modifications Copyright (C) 2021 Pantheon.tech
   4 #  Modifications Copyright (C) 2022 Bell Canada
   5 #  ================================================================================
   6 #  Licensed under the Apache License, Version 2.0 (the "License");
   7 #  you may not use this file except in compliance with the License.
   8 #  You may obtain a copy of the License at
   9 #
  10 #        http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 #  Unless required by applicable law or agreed to in writing, software
  13 #  distributed under the License is distributed on an "AS IS" BASIS,
  14 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 #  See the License for the specific language governing permissions and
  16 #  limitations under the License.
  17 #
  18 #  SPDX-License-Identifier: Apache-2.0
  19 #  ============LICENSE_END=========================================================
  20
  21 components:
  22   schemas:
  23     # Common Schemas
  24     ErrorMessage:
  25       type: object
  26       title: Error
  27       properties:
  28         status:
  29           type: string
  30         message:
  31           type: string
  32         details:
  33           type: string
  34     # DMI Server Exception Schema
  35     DmiErrorMessage:
  36       title: DMI Error Message
  37       type: object
  38       properties:
  39         message:
  40           type: string
  41           example: "Bad Gateway Error Message NCMP"
  42         dmi-response:
  43           type: object
  44           properties:
  45             http-code:
  46               type: integer
  47               example: 400
  48             body:
  49               type: string
  50               example: Bad Request
  51     # Request Schemas
  52     RestDmiPluginRegistration:
  53       type: object
  54       properties:
  55         dmiPlugin:
  56           type: string
  57           example: my-dmi-plugin
  58           default: ""
  59         dmiDataPlugin:
  60           type: string
  61           example: my-dmi-data-plugin
  62           default: ""
  63         dmiModelPlugin:
  64           type: string
  65           example: my-dmi-model-plugin
  66           default: ""
  67         createdCmHandles:
  68           type: array
  69           items:
  70             $ref: '#/components/schemas/RestInputCmHandle'
  71         updatedCmHandles:
  72           type: array
  73           items:
  74             $ref: '#/components/schemas/RestInputCmHandle'
  75             example:
  76               cmHandle: my-cm-handle
  77               cmHandleProperties:
  78                 add-my-property: add-property
  79                 update-my-property: updated-property
  80                 delete-my-property: '~'
  81               publicCmHandleProperties:
  82                 add-my-property: add-property
  83                 update-my-property: updated-property
  84                 delete-my-property: '~'
  85         removedCmHandles:
  86           type: array
  87           items:
  88             type: string
  89           example: [my-cm-handle1, my-cm-handle2, my-cm-handle3]
  90     DmiPluginRegistrationErrorResponse:
  91       type: object
  92       properties:
  93         failedCreatedCmHandles:
  94           type: array
  95           items:
  96             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
  97         failedUpdatedCmHandles:
  98           type: array
  99           items:
 100             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 101         failedRemovedCmHandles:
 102           type: array
 103           items:
 104             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 105     CmHandlerRegistrationErrorResponse:
 106       type: object
 107       properties:
 108         cmHandle:
 109           type: string
 110           example: my-cm-handle
 111         errorCode:
 112           type: string
 113           example: '00'
 114         errorText:
 115           type: string
 116           example: 'Unknown error. <error-details>'
 117
 118     RestInputCmHandle:
 119       required:
 120         - cmHandle
 121       type: object
 122       properties:
 123         cmHandle:
 124           type: string
 125           example: my-cm-handle
 126         cmHandleProperties:
 127             $ref: '#/components/schemas/RestCmHandleProperties'
 128         publicCmHandleProperties:
 129             $ref: '#/components/schemas/RestCmHandleProperties'
 130     RestCmHandleProperties:
 131         type: object
 132         additionalProperties:
 133             type: string
 134             example: my-property
 135
 136     Conditions:
 137       type: object
 138       properties:
 139         conditions:
 140           $ref: '#/components/schemas/ConditionsData'
 141     ConditionsData:
 142       type: array
 143       items:
 144         type: object
 145         $ref: '#/components/schemas/ConditionProperties'
 146     ConditionProperties:
 147       properties:
 148         name:
 149           type: string
 150           example: hasAllModules
 151         conditionParameters:
 152           $ref: '#/components/schemas/ModuleNamesAsJsonArray'
 153     ModuleNamesAsJsonArray:
 154       type: array
 155       items:
 156         type: object
 157         $ref: '#/components/schemas/ModuleNameAsJsonObject'
 158         example: [my-module-1, my-module-2, my-module-3]
 159     ModuleNameAsJsonObject:
 160         properties:
 161           moduleName:
 162             type: string
 163             example: my-module
 164
 165     #Response Schemas
 166     CmHandles:
 167       type: object
 168       properties:
 169         cmHandles:
 170           $ref: '#/components/schemas/CmHandleProperties'
 171     CmHandleProperties:
 172       type: array
 173       items:
 174         type: object
 175         $ref: '#/components/schemas/CmHandleProperty'
 176     CmHandleProperty:
 177       properties:
 178         cmHandleId:
 179           type: string
 180           example: my-cm-handle-id
 181
 182     RestModuleReference:
 183       type: object
 184       title: Module reference details
 185       properties:
 186         moduleName:
 187           type: string
 188           example: my-module-name
 189         revision:
 190           type: string
 191           example: my-module-revision
 192
 193     CmHandleQueryRestParameters:
 194       type: object
 195       title: Cm Handle query parameters for executing cm handle search
 196       properties:
 197         publicCmHandleProperties:
 198           type: object
 199           additionalProperties:
 200             type: string
 201             example: Book Type
 202
 203     RestOutputCmHandle:
 204       type: object
 205       title: CM handle Details
 206       properties:
 207         cmHandle:
 208           type: string
 209           example: my-cm-handle1
 210         publicCmHandleProperties:
 211           $ref: '#/components/schemas/CmHandlePublicProperties'
 212         state:
 213           $ref: '#/components/schemas/RestOutputCmHandleState'
 214     CmHandlePublicProperties:
 215       type: array
 216       items:
 217         type: object
 218         additionalProperties:
 219           type: string
 220           example: Book Type
 221     RestOutputCmHandleState:
 222       type: object
 223       properties:
 224         cmHandleState:
 225           type: string
 226           example: ADVISED
 227         lockReason:
 228           $ref: '#/components/schemas/lock-reason'
 229         lastUpdateTime:
 230           type: string
 231           example: 2022-12-31T20:30:40.000+0000
 232         dataSyncEnabled:
 233           type: boolean
 234           example: false
 235         dataSyncState:
 236           $ref: '#/components/schemas/dataStores'
 237
 238     lock-reason:
 239       type: object
 240       properties:
 241         reason:
 242           type: string
 243           example: LOCKED_OTHER
 244         details:
 245           type: string
 246           example: locked due to module sync
 247
 248     dataStores:
 249       type: object
 250       properties:
 251         operational:
 252           $ref: '#/components/schemas/sync-state'
 253         running:
 254           $ref: '#/components/schemas/sync-state'
 255
 256     sync-state:
 257       type: object
 258       properties:
 259         state:
 260           type: string
 261           example: NONE_REQUESTED
 262         lastSyncTime:
 263           type: string
 264           example: 2022-12-31T20:30:40.000+0000
 265
 266     RestOutputCmHandlePublicProperties:
 267       type: object
 268       properties:
 269         publicCmHandleProperties:
 270           $ref: '#/components/schemas/CmHandlePublicProperties'
 271
 272   examples:
 273     dataSampleRequest:
 274         summary: Sample request
 275         description: Sample request body
 276         value:
 277           test:bookstore:
 278             bookstore-name: Chapters
 279             categories:
 280               - code: '01'
 281                 name: SciFi
 282                 books:
 283                 - authors:
 284                     - Iain M. Banks
 285                     - Ursula K. Le Guin
 286               - code: '02'
 287                 name: kids
 288                 books:
 289                 - authors:
 290                     - Philip Pullman
 291
 292     dataSamplePatchRequest:
 293       summary: Sample patch request
 294       description: Sample patch request body
 295       value:
 296         ietf-restconf:yang-patch:
 297           patch-id: patch-1
 298           edit:
 299             - edit-id: edit1
 300               operation: merge
 301               target: /
 302               value:
 303                 test:bookstore:
 304                   bookstore-name: Chapters
 305                   categories:
 306                     - code: '01'
 307                       name: Science
 308                       books:
 309                         - authors:
 310                             - Author1
 311                             - Author2
 312                     - code: '02'
 313                       name: Arts
 314                       books:
 315                         - authors:
 316                             - Author3
 317             - edit-id: edit2
 318               operation: merge
 319               target: /
 320               value:
 321                 test:bookstore:
 322                   bookstore-name: Novels
 323                   categories:
 324                     - code: '03'
 325                       name: History
 326                       books:
 327                         - authors:
 328                             - Iain M. Banks
 329                             - Ursula K. Le Guin
 330                     - code: '04'
 331                       name: Fiction
 332                       books:
 333                         - authors:
 334                             - Philip Pullman
 335
 336     dataSampleResponse:
 337         summary: Sample response
 338         description: Sample response for selecting 'sample 1'.
 339         value:
 340           bookstore:
 341             categories:
 342               - code: '01'
 343                 books:
 344                   - authors:
 345                       - Iain M. Banks
 346                       - Ursula K. Le Guin
 347                 name: SciFi
 348               - code: '02'
 349                 books:
 350                   - authors:
 351                       - Philip Pullman
 352                 name: kids
 353
 354   parameters:
 355     cmHandleInPath:
 356       name: cm-handle
 357       in: path
 358       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 359       required: true
 360       schema:
 361         type: string
 362         example: my-cm-handle
 363     xpathInQuery:
 364       name: xpath
 365       in: query
 366       description: xpath
 367       required: false
 368       schema:
 369         type: string
 370         default: /
 371     requiredXpathInQuery:
 372       name: xpath
 373       in: query
 374       description: xpath
 375       required: true
 376       schema:
 377         type: string
 378     includeDescendantsOptionInQuery:
 379       name: include-descendants
 380       in: query
 381       description: include-descendants
 382       required: false
 383       schema:
 384         type: boolean
 385         default: false
 386     cpsPathInQuery:
 387       name: cps-path
 388       in: query
 389       description: cps-path
 390       required: false
 391       schema:
 392         type: string
 393         default: /
 394     resourceIdentifierInQuery:
 395       name: resourceIdentifier
 396       in: query
 397       description: The format of resource identifier depend on the associated DMI Plugin implementation. For ONAP DMI Plugin it will be RESTConf paths but it can really be anything.
 398       required: true
 399       allowReserved: true
 400       schema:
 401         type: string
 402       examples:
 403         sample 1:
 404           value:
 405             resourceIdentifier: \shops\bookstore
 406         sample 2:
 407           value:
 408             resourceIdentifier: \shops\bookstore\categories[@code=1]
 409         sample 3:
 410           value:
 411             resourceIdentifier: parent=shops,child=bookstore
 412     optionsParamInQuery:
 413       name: options
 414       in: query
 415       description: options parameter in query, it is mandatory to wrap key(s)=value(s) in parenthesis'()'. The format of options parameter depend on the associated DMI Plugin implementation.
 416       required: false
 417       schema:
 418         type: string
 419       allowReserved: true
 420       examples:
 421         sample 1:
 422           value:
 423             options: (depth=3)
 424         sample 2:
 425           value:
 426             options: (fields=book)
 427         sample 3:
 428           value:
 429             options: (depth=2,fields=book/authors)
 430     topicParamInQuery:
 431       name: topic
 432       in: query
 433       description: topic parameter in query.
 434       required: false
 435       schema:
 436         type: string
 437       allowReserved: true
 438       examples:
 439         sample 1:
 440           value:
 441             topic: my-topic-name
 442     contentParamInHeader:
 443       name: Content-Type
 444       in: header
 445       required: false
 446       description: Content parameter for request, if content parameter is null, default value is application/json.
 447       schema:
 448         type: string
 449         default: application/json
 450         example: application/yang-data+json
 451
 452   responses:
 453     NotFound:
 454       description: The specified resource was not found
 455       content:
 456         application/json:
 457           schema:
 458             $ref: '#/components/schemas/ErrorMessage'
 459           example:
 460             status: 400
 461             message: Not found error message
 462             details: Not found error details
 463     Unauthorized:
 464       description: Unauthorized
 465       content:
 466         application/json:
 467           schema:
 468             $ref: '#/components/schemas/ErrorMessage'
 469           example:
 470             status: 401
 471             message: Unauthorized error message
 472             details: Unauthorized error details
 473     Forbidden:
 474       description: Forbidden
 475       content:
 476         application/json:
 477           schema:
 478             $ref: '#/components/schemas/ErrorMessage'
 479           example:
 480            status: 403
 481            message: Forbidden error message
 482            details: Forbidden error details
 483     BadRequest:
 484       description: Bad Request
 485       content:
 486         application/json:
 487           schema:
 488             $ref: '#/components/schemas/ErrorMessage'
 489           example:
 490            status: 400 BAD_REQUEST
 491            message: Bad request error message
 492            details: Bad request error details
 493     Conflict:
 494       description: Conflict
 495       content:
 496         application/json:
 497           schema:
 498             $ref: '#/components/schemas/ErrorMessage'
 499           example:
 500            status: 409 CONFLICT
 501            message: Conflict error message
 502            details: Conflict error details
 503     NotImplemented:
 504       description: The given path has not been implemented
 505       content:
 506         application/json:
 507           schema:
 508             $ref: '#/components/schemas/ErrorMessage'
 509           example:
 510            status: 501
 511            message: Not implemented error message
 512            details: Not implemented error details
 513     Ok:
 514       description: OK
 515       content:
 516         application/json:
 517           schema:
 518             type: object
 519     Created:
 520       description: Created
 521       content: {}
 522     NoContent:
 523       description: No Content
 524       content: {}
 525     InternalServerError:
 526       description: Internal Server Error
 527       content:
 528         application/json:
 529           schema:
 530             $ref: "#/components/schemas/ErrorMessage"
 531           example:
 532             status: 500
 533             message: Internal Server Error
 534             details: Internal Server Error occurred
 535     BadGateway:
 536       description: Bad Gateway
 537       content:
 538         application/json:
 539           schema:
 540             $ref: "#/components/schemas/DmiErrorMessage"
 541           example:
 542             message: "Bad Gateway Error Message NCMP"
 543             dmi-response:
 544               http-code: 400
 545               body: "Bad Request"