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

#  ============LICENSE_START=======================================================
#  Copyright (C) 2021 Nordix Foundation
#  Modifications Copyright (C) 2021 Pantheon.tech
#  ================================================================================
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#        http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#
#  SPDX-License-Identifier: Apache-2.0
#  ============LICENSE_END=========================================================

components:
  schemas:
    # Common Schemas
    ErrorMessage:
      type: object
      title: Error
      properties:
        status:
          type: string
        message:
          type: string
        details:
          type: string

    # Request Schemas
    RestDmiPluginRegistration:
      type: object
      properties:
        dmiPlugin:
          type: string
          example: my-dmi-plugin
        dmiDataPlugin:
          type: string
          example: my-dmi-data-plugin
        dmiModelPlugin:
          type: string
          example: my-dmi-model-plugin
        createdCmHandles:
          type: array
          items:
            $ref: '#/components/schemas/RestCmHandle'
          example: [my-cm-handle1, my-cm-handle2, my-cm-handle3]
        updatedCmHandles:
          type: array
          items:
            $ref: '#/components/schemas/RestCmHandle'
        removedCmHandles:
          type: array
          items:
            type: string
            example: [my-cm-handle1, my-cm-handle2, my-cm-handle3]

    RestCmHandle:
      required:
        - cmHandle
      type: object
      properties:
        cmHandle:
          type: string
          example: my-cm-handle
        cmHandleProperties:
            $ref: '#/components/schemas/RestCmHandleAdditionalProperties'
    RestCmHandleAdditionalProperties:
        type: object
        additionalProperties:
            type: string
            example: my-additional-property

    Conditions:
      type: object
      properties:
        conditions:
          $ref: '#/components/schemas/ConditionsData'
    ConditionsData:
      type: array
      items:
        type: object
        $ref: '#/components/schemas/ConditionProperties'
    ConditionProperties:
      properties:
        name:
          type: string
          example: hasAllModules
        conditionParameters:
          $ref: '#/components/schemas/ModuleNamesAsJsonArray'
    ModuleNamesAsJsonArray:
      type: array
      items:
        type: object
        $ref: '#/components/schemas/ModuleNameAsJsonObject'
        example: [my-module-1, my-module-2, my-module-3]
    ModuleNameAsJsonObject:
        properties:
          moduleName:
            type: string
            example: my-module

    #Response Schemas
    CmHandles:
      type: object
      properties:
        cmHandles:
          $ref: '#/components/schemas/CmHandleProperties'
    CmHandleProperties:
      type: array
      items:
        type: object
        $ref: '#/components/schemas/CmHandleProperty'
    CmHandleProperty:
      properties:
        cmHandleId:
          type: string
          example: my-cm-handle-id

  examples:
    dataSampleRequest:
        summary: Sample request
        description: Sample request body
        value:
          test:bookstore:
            bookstore-name: Chapters
            categories:
              - code: '01'
                name: SciFi
                books:
                - authors:
                    - Iain M. Banks
                - authors:
                    - Ursula K. Le Guin
              - code: '02'
                name: kids
                books:
                - authors:
                    - Philip Pullman

    dataSampleResponse:
        summary: Sample response
        description: Sample response for selecting 'sample 1'.
        value:
          bookstore:
            categories:
              - code: '01'
                books:
                  - {}
                  - {}
                name: SciFi
              - code: '02'
                books:
                  - {}
                name: kids
            bookstore-name: Chapters

  parameters:
    cmHandleInPath:
      name: cm-handle
      in: path
      description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
      required: true
      schema:
        type: string
        example: my-cm-handle
    xpathInQuery:
      name: xpath
      in: query
      description: xpath
      required: false
      schema:
        type: string
        default: /
    requiredXpathInQuery:
      name: xpath
      in: query
      description: xpath
      required: true
      schema:
        type: string
    includeDescendantsOptionInQuery:
      name: include-descendants
      in: query
      description: include-descendants
      required: false
      schema:
        type: boolean
        default: false
    cpsPathInQuery:
      name: cps-path
      in: query
      description: cps-path
      required: false
      schema:
        type: string
        default: /
    resourceIdentifierInQuery:
      name: resourceIdentifier
      in: query
      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.
      required: true
      allowReserved: true
      schema:
        type: string
      examples:
        sample 1:
          value:
            resourceIdentifier: \shops\bookstore
        sample 2:
          value:
            resourceIdentifier: \shops\bookstore\categories[@code=1]
        sample 3:
          value:
            resourceIdentifier: parent=shops,child=bookstore
    acceptParamInHeader:
      name: Accept
      in: header
      required: false
      description: Accept parameter for response, if accept parameter is null, that means client can accept any format.
      schema:
        type: string
        enum: [ application/json, application/yang-data+json ]
    optionsParamInQuery:
      name: options
      in: query
      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.
      required: false
      schema:
        type: string
      allowReserved: true
      examples:
        sample 1:
          value:
            options: (depth=3)
        sample 2:
          value:
            options: (fields=book)
        sample 3:
          value:
            options: (depth=2,fields=book/authors)
    contentParamInHeader:
      name: Content-Type
      in: header
      required: false
      description: Content parameter for request, if content parameter is null, default value is application/json.
      schema:
        type: string
        default: application/json
        example: application/yang-data+json

  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            status: 400
            message: Not found error message
            details: Not found error details
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            status: 401
            message: Unauthorized error message
            details: Unauthorized error details
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
           status: 403
           message: Forbidden error message
           details: Forbidden error details
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
           status: 400 BAD_REQUEST
           message: Bad request error message
           details: Bad request error details
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
           status: 409 CONFLICT
           message: Conflict error message
           details: Conflict error details
    NotImplemented:
      description: The given path has not been implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
           status: 501
           message: Not implemented error message
           details: Not implemented error details
    Ok:
      description: OK
      content:
        application/json:
          schema:
            type: object
    Created:
      description: Created
      content: {}
    NoContent:
      description: No Content
      content: {}