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