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