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           example: [
  98             {
  99               "cmHandle": "my-cm-handle-01",
 100               "errorCode": "01",
 101               "errorText": "cm-handle already exists"
 102             }
 103           ]
 104         failedUpdatedCmHandles:
 105           type: array
 106           items:
 107             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 108           example: [
 109             {
 110               "cmHandle": "my-cm-handle-02",
 111               "errorCode": "02",
 112               "errorText": "cm-handle does not exist"
 113             }
 114           ]
 115         failedRemovedCmHandles:
 116           type: array
 117           items:
 118             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 119           example: [
 120             {
 121               "cmHandle": "my-cm-handle-02",
 122               "errorCode": "02",
 123               "errorText": "cm-handle does not exist"
 124             }
 125           ]
 126     CmHandlerRegistrationErrorResponse:
 127       type: object
 128       properties:
 129         cmHandle:
 130           type: string
 131           example: my-cm-handle
 132         errorCode:
 133           type: string
 134           example: '01'
 135         errorText:
 136           type: string
 137           example: 'cm-handle already exists'
 138
 139     RestInputCmHandle:
 140       required:
 141         - cmHandle
 142       type: object
 143       properties:
 144         cmHandle:
 145           type: string
 146           example: my-cm-handle
 147         cmHandleProperties:
 148             $ref: '#/components/schemas/RestCmHandleProperties'
 149         publicCmHandleProperties:
 150             $ref: '#/components/schemas/RestCmHandleProperties'
 151     RestCmHandleProperties:
 152         type: object
 153         additionalProperties:
 154             type: string
 155             example: my-property
 156
 157     Conditions:
 158       type: object
 159       properties:
 160         conditions:
 161           $ref: '#/components/schemas/ConditionsData'
 162     ConditionsData:
 163       type: array
 164       items:
 165         type: object
 166         $ref: '#/components/schemas/ConditionProperties'
 167     ConditionProperties:
 168       properties:
 169         name:
 170           type: string
 171           example: hasAllModules
 172         conditionParameters:
 173           $ref: '#/components/schemas/ModuleNamesAsJsonArray'
 174     ModuleNamesAsJsonArray:
 175       type: array
 176       items:
 177         type: object
 178         $ref: '#/components/schemas/ModuleNameAsJsonObject'
 179         example: [my-module-1, my-module-2, my-module-3]
 180     ModuleNameAsJsonObject:
 181         properties:
 182           moduleName:
 183             type: string
 184             example: my-module
 185
 186     #Response Schemas
 187     CmHandles:
 188       type: object
 189       properties:
 190         cmHandles:
 191           $ref: '#/components/schemas/CmHandleProperties'
 192     CmHandleProperties:
 193       type: array
 194       items:
 195         type: object
 196         $ref: '#/components/schemas/CmHandleProperty'
 197     CmHandleProperty:
 198       properties:
 199         cmHandleId:
 200           type: string
 201           example: my-cm-handle-id
 202
 203     RestModuleReference:
 204       type: object
 205       title: Module reference details
 206       properties:
 207         moduleName:
 208           type: string
 209           example: my-module-name
 210         revision:
 211           type: string
 212           example: my-module-revision
 213
 214     CmHandleQueryRestParameters:
 215       type: object
 216       title: Cm Handle query parameters for executing cm handle search
 217       properties:
 218         publicCmHandleProperties:
 219           type: object
 220           additionalProperties:
 221             type: string
 222             example: Book Type
 223
 224     RestOutputCmHandle:
 225       type: object
 226       title: CM handle Details
 227       properties:
 228         cmHandle:
 229           type: string
 230           example: my-cm-handle1
 231         publicCmHandleProperties:
 232           $ref: '#/components/schemas/CmHandlePublicProperties'
 233     CmHandlePublicProperties:
 234       type: array
 235       items:
 236         type: object
 237         additionalProperties:
 238           type: string
 239           example: Book Type
 240
 241   examples:
 242     dataSampleRequest:
 243         summary: Sample request
 244         description: Sample request body
 245         value:
 246           test:bookstore:
 247             bookstore-name: Chapters
 248             categories:
 249               - code: '01'
 250                 name: SciFi
 251                 books:
 252                 - authors:
 253                     - Iain M. Banks
 254                     - Ursula K. Le Guin
 255               - code: '02'
 256                 name: kids
 257                 books:
 258                 - authors:
 259                     - Philip Pullman
 260
 261     dataSamplePatchRequest:
 262       summary: Sample patch request
 263       description: Sample patch request body
 264       value:
 265         ietf-restconf:yang-patch:
 266           patch-id: patch-1
 267           edit:
 268             - edit-id: edit1
 269               operation: merge
 270               target: /
 271               value:
 272                 test:bookstore:
 273                   bookstore-name: Chapters
 274                   categories:
 275                     - code: '01'
 276                       name: Science
 277                       books:
 278                         - authors:
 279                             - Author1
 280                             - Author2
 281                     - code: '02'
 282                       name: Arts
 283                       books:
 284                         - authors:
 285                             - Author3
 286             - edit-id: edit2
 287               operation: merge
 288               target: /
 289               value:
 290                 test:bookstore:
 291                   bookstore-name: Novels
 292                   categories:
 293                     - code: '03'
 294                       name: History
 295                       books:
 296                         - authors:
 297                             - Iain M. Banks
 298                             - Ursula K. Le Guin
 299                     - code: '04'
 300                       name: Fiction
 301                       books:
 302                         - authors:
 303                             - Philip Pullman
 304
 305     dataSampleResponse:
 306         summary: Sample response
 307         description: Sample response for selecting 'sample 1'.
 308         value:
 309           bookstore:
 310             categories:
 311               - code: '01'
 312                 books:
 313                   - authors:
 314                       - Iain M. Banks
 315                       - Ursula K. Le Guin
 316                 name: SciFi
 317               - code: '02'
 318                 books:
 319                   - authors:
 320                       - Philip Pullman
 321                 name: kids
 322
 323   parameters:
 324     cmHandleInPath:
 325       name: cm-handle
 326       in: path
 327       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 328       required: true
 329       schema:
 330         type: string
 331         example: my-cm-handle
 332     xpathInQuery:
 333       name: xpath
 334       in: query
 335       description: xpath
 336       required: false
 337       schema:
 338         type: string
 339         default: /
 340     requiredXpathInQuery:
 341       name: xpath
 342       in: query
 343       description: xpath
 344       required: true
 345       schema:
 346         type: string
 347     includeDescendantsOptionInQuery:
 348       name: include-descendants
 349       in: query
 350       description: include-descendants
 351       required: false
 352       schema:
 353         type: boolean
 354         default: false
 355     cpsPathInQuery:
 356       name: cps-path
 357       in: query
 358       description: cps-path
 359       required: false
 360       schema:
 361         type: string
 362         default: /
 363     resourceIdentifierInQuery:
 364       name: resourceIdentifier
 365       in: query
 366       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.
 367       required: true
 368       allowReserved: true
 369       schema:
 370         type: string
 371       examples:
 372         sample 1:
 373           value:
 374             resourceIdentifier: \shops\bookstore
 375         sample 2:
 376           value:
 377             resourceIdentifier: \shops\bookstore\categories[@code=1]
 378         sample 3:
 379           value:
 380             resourceIdentifier: parent=shops,child=bookstore
 381     optionsParamInQuery:
 382       name: options
 383       in: query
 384       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.
 385       required: false
 386       schema:
 387         type: string
 388       allowReserved: true
 389       examples:
 390         sample 1:
 391           value:
 392             options: (depth=3)
 393         sample 2:
 394           value:
 395             options: (fields=book)
 396         sample 3:
 397           value:
 398             options: (depth=2,fields=book/authors)
 399     topicParamInQuery:
 400       name: topic
 401       in: query
 402       description: topic parameter in query.
 403       required: false
 404       schema:
 405         type: string
 406       allowReserved: true
 407       examples:
 408         sample 1:
 409           value:
 410             topic: my-topic-name
 411     contentParamInHeader:
 412       name: Content-Type
 413       in: header
 414       required: false
 415       description: Content parameter for request, if content parameter is null, default value is application/json.
 416       schema:
 417         type: string
 418         default: application/json
 419         example: application/yang-data+json
 420
 421   responses:
 422     NotFound:
 423       description: The specified resource was not found
 424       content:
 425         application/json:
 426           schema:
 427             $ref: '#/components/schemas/ErrorMessage'
 428           example:
 429             status: 400
 430             message: Not found error message
 431             details: Not found error details
 432     Unauthorized:
 433       description: Unauthorized
 434       content:
 435         application/json:
 436           schema:
 437             $ref: '#/components/schemas/ErrorMessage'
 438           example:
 439             status: 401
 440             message: Unauthorized error message
 441             details: Unauthorized error details
 442     Forbidden:
 443       description: Forbidden
 444       content:
 445         application/json:
 446           schema:
 447             $ref: '#/components/schemas/ErrorMessage'
 448           example:
 449            status: 403
 450            message: Forbidden error message
 451            details: Forbidden error details
 452     BadRequest:
 453       description: Bad Request
 454       content:
 455         application/json:
 456           schema:
 457             $ref: '#/components/schemas/ErrorMessage'
 458           example:
 459            status: 400 BAD_REQUEST
 460            message: Bad request error message
 461            details: Bad request error details
 462     Conflict:
 463       description: Conflict
 464       content:
 465         application/json:
 466           schema:
 467             $ref: '#/components/schemas/ErrorMessage'
 468           example:
 469            status: 409 CONFLICT
 470            message: Conflict error message
 471            details: Conflict error details
 472     NotImplemented:
 473       description: The given path has not been implemented
 474       content:
 475         application/json:
 476           schema:
 477             $ref: '#/components/schemas/ErrorMessage'
 478           example:
 479            status: 501
 480            message: Not implemented error message
 481            details: Not implemented error details
 482     Ok:
 483       description: OK
 484       content:
 485         application/json:
 486           schema:
 487             type: object
 488     Created:
 489       description: Created
 490       content: {}
 491     NoContent:
 492       description: No Content
 493       content: {}
 494     InternalServerError:
 495       description: Internal Server Error
 496       content:
 497         application/json:
 498           schema:
 499             $ref: "#/components/schemas/ErrorMessage"
 500           example:
 501             status: 500
 502             message: Internal Server Error
 503             details: Internal Server Error occurred
 504     BadGateway:
 505       description: Bad Gateway
 506       content:
 507         application/json:
 508           schema:
 509             $ref: "#/components/schemas/DmiErrorMessage"
 510           example:
 511             message: "Bad Gateway Error Message NCMP"
 512             dmi-response:
 513               http-code: 400
 514               body: "Bad Request"