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