Add documentation

Issue-ID: DCAEGEN2-206
Change-Id: I73de95e98e4cd545dcc29b0fcecf84530c23e2aa
Signed-off-by: Lusheng Ji <lji@research.att.com>

1 files changed, 697 insertions, 0 deletions

diff --git a/docs/sections/apis/swagger_inventory.yaml b/docs/sections/apis/swagger_inventory.yaml
new file mode 100644
index 00000000..068f2216
--- /dev/null
+++ b/docs/sections/apis/swagger_inventory.yaml
@@ -0,0 +1,697 @@
+# ================================================================================
+# Copyright (c) 2017-2018 AT&T Intellectual Property. All rights reserved.
+# ================================================================================
+# 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.
+# ============LICENSE_END=========================================================
+#
+# ECOMP is a trademark and service mark of AT&T Intellectual Property.
+swagger: '2.0'
+info:
+  version: "2.1.0"
+  title: DCAE Inventory API
+  description: |
+    DCAE Inventory is a web service that provides the following:
+
+    1. Real-time data on all DCAE services and their components
+    2. Comprehensive details on available DCAE service types
+  contact:
+    email: dcae@lists.openecomp.org
+externalDocs:
+  description: DCAE Inventory
+  url: https://gerrit.onap.org/r/#/admin/projects/dcae/dcae-inventory
+paths:
+  /dcae-service-types:
+    get:
+      summary: ""
+      description: "Get a list of `DCAEServiceType` objects."
+      operationId: "dcaeServiceTypesGet"
+      consumes:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      produces:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      parameters:
+      - name: "typeName"
+        in: "query"
+        description: "Filter by service type name"
+        required: false
+        type: "string"
+      - name: "onlyLatest"
+        in: "query"
+        description: "If set to true, query returns just the latest versions of DCAE\
+          \ service types. If set to false, then all versions are returned. Default\
+          \ is true"
+        required: false
+        type: "boolean"
+        default: true
+      - name: "onlyActive"
+        in: "query"
+        description: "If set to true, query returns only *active* DCAE service types.\
+          \ If set to false, then all DCAE service types are returned. Default is\
+          \ true"
+        required: false
+        type: "boolean"
+        default: true
+      - name: "vnfType"
+        in: "query"
+        description: "Filter by associated vnf type. No wildcards, matches are explicit.\
+          \ This field is treated case insensitive."
+        required: false
+        type: "string"
+      - name: "serviceId"
+        in: "query"
+        description: "Filter by assocaited service id. Instances with service id null\
+          \ or empty is always returned."
+        required: false
+        type: "string"
+      - name: "serviceLocation"
+        in: "query"
+        description: "Filter by associated service location. Instances with service\
+          \ location null or empty is always returned."
+        required: false
+        type: "string"
+      - name: "asdcServiceId"
+        in: "query"
+        description: "Filter by associated asdc design service id. Setting this to\
+          \ `NONE` will return instances that have asdc service id set to null"
+        required: false
+        type: "string"
+      - name: "asdcResourceId"
+        in: "query"
+        description: "Filter by associated asdc design resource id. Setting this to\
+          \ `NONE` will return instances that have asdc resource id set to null"
+        required: false
+        type: "string"
+      - name: "offset"
+        in: "query"
+        description: "Query resultset offset used for pagination (zero-based)"
+        required: false
+        type: "integer"
+        format: "int32"
+      responses:
+        200:
+          description: "List of `DCAEServiceType` objects"
+          schema:
+            $ref: "#/definitions/InlineResponse200"
+    post:
+      summary: ""
+      description: "Inserts a new `DCAEServiceType` or updates an existing instance.\
+        \ Updates are only allowed iff there are no running DCAE services of the requested\
+        \ type,"
+      operationId: "dcaeServiceTypesTypeNamePut"
+      consumes:
+      - "application/json"
+      produces:
+      - "application/json"
+      parameters:
+      - in: "body"
+        name: "body"
+        required: true
+        schema:
+          $ref: "#/definitions/DCAEServiceTypeRequest"
+      responses:
+        200:
+          description: "Single `DCAEServiceType` object."
+          schema:
+            $ref: "#/definitions/DCAEServiceType"
+        400:
+          description: "Bad request provided."
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+        409:
+          description: "Failed to update because there are still DCAE services of\
+            \ the requested type running."
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+  /dcae-service-types/{typeId}:
+    get:
+      summary: ""
+      description: "Get a `DCAEServiceType` object."
+      operationId: "dcaeServiceTypesTypeIdGet"
+      consumes:
+      - "application/json"
+      produces:
+      - "application/json"
+      parameters:
+      - name: "typeId"
+        in: "path"
+        required: true
+        type: "string"
+      responses:
+        200:
+          description: "Single `DCAEServiceType` object"
+          schema:
+            $ref: "#/definitions/DCAEServiceType"
+        404:
+          description: "Resource not found"
+          schema:
+            $ref: "#/definitions/DCAEServiceType"
+    delete:
+      summary: ""
+      description: "Deactivates existing `DCAEServiceType` instances"
+      operationId: "dcaeServiceTypesTypeIdDelete"
+      consumes:
+      - "application/vnd.dcae.inventory.v1+json"
+      - "application/json"
+      produces:
+      - "application/vnd.dcae.inventory.v1+json"
+      - "application/json"
+      parameters:
+      - name: "typeId"
+        in: "path"
+        required: true
+        type: "string"
+      responses:
+        200:
+          description: "`DCAEServiceType` has been deactivated"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+        410:
+          description: "`DCAEServiceType` already gone"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+        404:
+          description: "`DCAEServiceType` not found"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+  /dcae-services:
+    get:
+      summary: ""
+      description: "Get a list of `DCAEService` objects."
+      operationId: "dcaeServicesGet"
+      consumes:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      produces:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      parameters:
+      - name: "typeId"
+        in: "query"
+        description: "DCAE service type name"
+        required: false
+        type: "string"
+      - name: "vnfId"
+        in: "query"
+        required: false
+        type: "string"
+      - name: "vnfType"
+        in: "query"
+        description: "Filter by associated vnf type. This field is treated case insensitive."
+        required: false
+        type: "string"
+      - name: "vnfLocation"
+        in: "query"
+        required: false
+        type: "string"
+      - name: "componentType"
+        in: "query"
+        description: "Use to filter by a specific DCAE service component type"
+        required: false
+        type: "string"
+      - name: "shareable"
+        in: "query"
+        description: "Use to filter by DCAE services that have shareable components\
+          \ or not"
+        required: false
+        type: "boolean"
+      - name: "created"
+        in: "query"
+        description: "Use to filter by created time"
+        required: false
+        type: "string"
+      - name: "offset"
+        in: "query"
+        description: "Query resultset offset used for pagination (zero-based)"
+        required: false
+        type: "integer"
+        format: "int32"
+      responses:
+        200:
+          description: "List of `DCAEService` objects"
+          schema:
+            $ref: "#/definitions/InlineResponse2001"
+        502:
+          description: "Bad response from DCAE controller"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+        504:
+          description: "Failed to connect with DCAE controller"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+  /dcae-services-groupby/{propertyName}:
+    get:
+      summary: ""
+      description: "Get a list of unique values for the given `propertyName`"
+      operationId: "dcaeServicesGroupbyPropertyNameGet"
+      consumes:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      produces:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      parameters:
+      - name: "propertyName"
+        in: "path"
+        description: "Property to find unique values. Restricted to `type`, `vnfType`,\
+          \ `vnfLocation`"
+        required: true
+        type: "string"
+      responses:
+        200:
+          description: "List of unique property values"
+          schema:
+            $ref: "#/definitions/DCAEServiceGroupByResults"
+  /dcae-services/{serviceId}:
+    get:
+      summary: ""
+      description: "Get a `DCAEService` object."
+      operationId: "dcaeServicesServiceIdGet"
+      consumes:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      produces:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      parameters:
+      - name: "serviceId"
+        in: "path"
+        required: true
+        type: "string"
+      responses:
+        200:
+          description: "Single `DCAEService` object"
+          schema:
+            $ref: "#/definitions/DCAEService"
+        502:
+          description: "Bad response from DCAE controller"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+        404:
+          description: "DCAE service not found"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+        504:
+          description: "Failed to connect with DCAE controller"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+    put:
+      summary: ""
+      description: "Put a new or update an existing `DCAEService` object."
+      operationId: "dcaeServicesServiceIdPut"
+      consumes:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      produces:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      parameters:
+      - name: "serviceId"
+        in: "path"
+        required: true
+        type: "string"
+      - in: "body"
+        name: "body"
+        required: true
+        schema:
+          $ref: "#/definitions/DCAEServiceRequest"
+      responses:
+        200:
+          description: "Single `DCAEService` object"
+          schema:
+            $ref: "#/definitions/DCAEService"
+        422:
+          description: "Bad request provided"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+    delete:
+      summary: ""
+      description: "Remove an existing `DCAEService` object."
+      operationId: "dcaeServicesServiceIdDelete"
+      consumes:
+      - "application/vnd.dcae.inventory.v1+json"
+      - "application/json"
+      produces:
+      - "application/json"
+      - "application/vnd.dcae.inventory.v1+json"
+      parameters:
+      - name: "serviceId"
+        in: "path"
+        required: true
+        type: "string"
+      responses:
+        200:
+          description: "DCAE service has been removed"
+        404:
+          description: "Unknown DCAE service"
+          schema:
+            $ref: "#/definitions/ApiResponseMessage"
+definitions:
+  DCAEServiceTypeRequest:
+    type: "object"
+    required:
+    - "blueprintTemplate"
+    - "owner"
+    - "typeName"
+    - "typeVersion"
+    properties:
+      owner:
+        type: "string"
+      typeName:
+        type: "string"
+        description: "Descriptive name for this DCAE service type"
+      typeVersion:
+        type: "integer"
+        format: "int32"
+        description: "Version number for this DCAE service type"
+      blueprintTemplate:
+        type: "string"
+        description: "String representation of a Cloudify blueprint with unbound variables"
+      serviceIds:
+        type: "array"
+        description: "List of service ids that are used to associate with DCAE service\
+          \ type. DCAE service types with this propery as null or empty means them\
+          \ apply for every service id."
+        items:
+          type: "string"
+      vnfTypes:
+        type: "array"
+        items:
+          type: "string"
+      serviceLocations:
+        type: "array"
+        description: "List of service locations that are used to associate with DCAE\
+          \ service type. DCAE service types with this propery as null or empty means\
+          \ them apply for every service location."
+        items:
+          type: "string"
+      asdcServiceId:
+        type: "string"
+        description: "Id of service this DCAE service type is associated with. Value\
+          \ source is from ASDC's notification event's field `serviceInvariantUUID`."
+      asdcResourceId:
+        type: "string"
+        description: "Id of vf/vnf instance this DCAE service type is associated with.\
+          \ Value source is from ASDC's notification event's field `resourceInvariantUUID`."
+      asdcServiceURL:
+        type: "string"
+        description: "URL to the ASDC service model"
+  DCAEServiceComponentRequest:
+    type: "object"
+    required:
+    - "componentId"
+    - "componentSource"
+    - "componentType"
+    - "shareable"
+    properties:
+      componentId:
+        type: "string"
+        description: "The id format is unique to the source"
+      componentType:
+        type: "string"
+      componentSource:
+        type: "string"
+        description: "Specifies the name of the underying source service that is responsible\
+          \ for this components"
+        enum:
+        - "DCAEController"
+        - "DMaaPController"
+      shareable:
+        type: "integer"
+        format: "int32"
+        description: "Used to determine if this component can be shared amongst different\
+          \ DCAE services"
+  DCAEServiceGroupByResultsPropertyValues:
+    type: "object"
+    properties:
+      count:
+        type: "integer"
+        format: "int32"
+      propertyValue:
+        type: "string"
+      dcaeServiceQueryLink:
+        description: "Link.title is the DCAE service property value. Following this\
+          \ link will provide a list of DCAE services that all have this property\
+          \ value."
+        $ref: "#/definitions/Link"
+  DCAEServiceGroupByResults:
+    type: "object"
+    properties:
+      propertyName:
+        type: "string"
+        description: "Property name of DCAE service that the group by operation was\
+          \ performed on"
+      propertyValues:
+        type: "array"
+        items:
+          $ref: "#/definitions/DCAEServiceGroupByResultsPropertyValues"
+  InlineResponse200:
+    type: "object"
+    properties:
+      links:
+        $ref: "#/definitions/InlineResponse200Links"
+      totalCount:
+        type: "integer"
+        format: "int32"
+      items:
+        type: "array"
+        items:
+          $ref: "#/definitions/DCAEServiceType"
+  DCAEServiceRequest:
+    type: "object"
+    required:
+    - "components"
+    - "typeId"
+    - "vnfId"
+    - "vnfLocation"
+    - "vnfType"
+    properties:
+      typeId:
+        type: "string"
+        description: "Id of the associated DCAE service type"
+      vnfId:
+        type: "string"
+        description: "Id of the associated VNF that this service is monitoring"
+      vnfType:
+        type: "string"
+        description: "The type of the associated VNF that this service is monitoring"
+      vnfLocation:
+        type: "string"
+        description: "Location identifier of the associated VNF that this service\
+          \ is monitoring"
+      deploymentRef:
+        type: "string"
+        description: "Reference to a Cloudify deployment"
+      components:
+        type: "array"
+        description: "List of DCAE service components that this service is composed\
+          \ of"
+        items:
+          $ref: "#/definitions/DCAEServiceComponentRequest"
+  InlineResponse200Links:
+    type: "object"
+    properties:
+      previousLink:
+        $ref: "#/definitions/Link"
+      nextLink:
+        $ref: "#/definitions/Link"
+    description: "Pagination links"
+  ApiResponseMessage:
+    type: "object"
+    properties:
+      code:
+        type: "integer"
+        format: "int32"
+      type:
+        type: "string"
+      message:
+        type: "string"
+  DCAEService:
+    type: "object"
+    properties:
+      serviceId:
+        type: "string"
+      selfLink:
+        description: "Link.title is serviceId"
+        $ref: "#/definitions/Link"
+      created:
+        type: "string"
+        format: "date-time"
+      modified:
+        type: "string"
+        format: "date-time"
+      typeLink:
+        description: "Link.title is typeId"
+        $ref: "#/definitions/Link"
+      vnfId:
+        type: "string"
+      vnfLink:
+        description: "Link.title is vnfId"
+        $ref: "#/definitions/Link"
+      vnfType:
+        type: "string"
+      vnfLocation:
+        type: "string"
+        description: "Location information of the associated VNF"
+      deploymentRef:
+        type: "string"
+        description: "Reference to a Cloudify deployment"
+      components:
+        type: "array"
+        items:
+          $ref: "#/definitions/DCAEServiceComponent"
+  InlineResponse2001:
+    type: "object"
+    properties:
+      links:
+        $ref: "#/definitions/InlineResponse200Links"
+      totalCount:
+        type: "integer"
+        format: "int32"
+      items:
+        type: "array"
+        items:
+          $ref: "#/definitions/DCAEService"
+  UriBuilder:
+    type: "object"
+  Link:
+    type: "object"
+    properties:
+      title:
+        type: "string"
+      rel:
+        type: "string"
+      uri:
+        type: "string"
+        format: "uri"
+      uriBuilder:
+        $ref: "#/definitions/UriBuilder"
+      rels:
+        type: "array"
+        items:
+          type: "string"
+      params:
+        type: "object"
+        additionalProperties:
+          type: "string"
+      type:
+        type: "string"
+  DCAEServiceComponent:
+    type: "object"
+    required:
+    - "componentId"
+    - "componentLink"
+    - "componentSource"
+    - "componentType"
+    - "created"
+    - "modified"
+    - "shareable"
+    properties:
+      componentId:
+        type: "string"
+        description: "The id format is unique to the source"
+      componentLink:
+        description: "Link to the underlying resource of this component"
+        $ref: "#/definitions/Link"
+      created:
+        type: "string"
+        format: "date-time"
+      modified:
+        type: "string"
+        format: "date-time"
+      componentType:
+        type: "string"
+      componentSource:
+        type: "string"
+        description: "Specifies the name of the underying source service that is responsible\
+          \ for this components"
+        enum:
+        - "DCAEController"
+        - "DMaaPController"
+      status:
+        type: "string"
+      location:
+        type: "string"
+        description: "Location information of the component"
+      shareable:
+        type: "integer"
+        format: "int32"
+        description: "Used to determine if this component can be shared amongst different\
+          \ DCAE services"
+  DCAEServiceType:
+    type: "object"
+    required:
+    - "blueprintTemplate"
+    - "created"
+    - "owner"
+    - "selfLink"
+    - "typeId"
+    - "typeName"
+    - "typeVersion"
+    properties:
+      owner:
+        type: "string"
+      typeName:
+        type: "string"
+        description: "Descriptive name for this DCAE service type"
+      typeVersion:
+        type: "integer"
+        format: "int32"
+        description: "Version number for this DCAE service type"
+      blueprintTemplate:
+        type: "string"
+        description: "String representation of a Cloudify blueprint with unbound variables"
+      serviceIds:
+        type: "array"
+        description: "List of service ids that are used to associate with DCAE service\
+          \ type. DCAE service types with this propery as null or empty means them\
+          \ apply for every service id."
+        items:
+          type: "string"
+      vnfTypes:
+        type: "array"
+        items:
+          type: "string"
+      serviceLocations:
+        type: "array"
+        description: "List of service locations that are used to associate with DCAE\
+          \ service type. DCAE service types with this propery as null or empty means\
+          \ them apply for every service location."
+        items:
+          type: "string"
+      asdcServiceId:
+        type: "string"
+        description: "Id of service this DCAE service type is associated with. Value\
+          \ source is from ASDC's notification event's field `serviceInvariantUUID`."
+      asdcResourceId:
+        type: "string"
+        description: "Id of vf/vnf instance this DCAE service type is associated with.\
+          \ Value source is from ASDC's notification event's field `resourceInvariantUUID`."
+      asdcServiceURL:
+        type: "string"
+        description: "URL to the ASDC service model"
+      typeId:
+        type: "string"
+        description: "Unique identifier for this DCAE service type"
+      selfLink:
+        description: "Link to self where the Link.title is typeName"
+        $ref: "#/definitions/Link"
+      created:
+        type: "string"
+        format: "date-time"
+        description: "Created timestamp for this DCAE service type in epoch time"
+      deactivated:
+        type: "string"
+        format: "date-time"
+        description: "Deactivated timestamp for this DCAE service type in epoch time"