OpenAPI Belirtimi Oluşturma

Becerileri OpenAPI Belirtim (OAS) dosyalarından içe aktarabilirsiniz. OAS dosyası, Watson Orchestra 'da uygulamaya ve becerilere dönüştürülür. Bu belge, Watson Orchestra 'da içe aktarılacak OAS ' ın nasıl oluşturulacağını açıklar.

Başlamadan önce

  • Watson Orchestrate üzerinde oluşturucu erişimine sahip olmanız gerekir.
  • YAML ya da JSON biçimlerini destekleyen bir metin dosyası düzenleyicisine gereksinim duyarsınız.

OpenAPI sürümünü yapılandırma

Watson Orchestrate olarak içe aktarmak için OAS ' ınızda kullanılan sürümü ayarlayın. Sürümü openapi nesnesini kullanarak ayarlayabilirsiniz.

Watson Orchestra 'ya içe aktarma için OAS geçerliliğini döndürmek üzere 3.x sürümünü ya da üstünü kullanmanız gerekir.

Aşağıdaki örnekte, 3.0.2 OAS sürümünü ayarlamak için openapi nesnesinin nasıl kullanılacağı gösterilmektedir.

  • "openapi": "3.0.2"

  • openapi: 3.0.2

Uygulamayı yapılandırma

info nesnesini kullanarak becerilerinizin uygulamasını yapılandırabilirsiniz. info nesnesi, OAS meta verilerini sağlar. Meta veriler, uygulamayı Watson Düzenlemede oluşturmak için kullanılır.

Aşağıdaki tabloda, Watson Düzenlemede uygulamayı oluşturmak için kullanılan özellikler açıklanmaktadır.

Eğilim Zorunlu Açıklama
başlık evet Uygulama başlığını tanımlar. Bu özellik, x-ibm-application-name özelliğini ayarlamazsanız Watson Orchestra 'da uygulama adını da tanımlar.

Uygulama başlığını yapılandırma
açıklama hayır Uygulama açıklamasını tanımlar.
sürüm evet Uygulama sürümünü tanımlar.

Aşağıdaki örnekte, Pet shot uygulamasını yapılandırmak için info nesnesinin nasıl kullanılacağı gösterilmektedir.

  • "info": {
    "title": "Swagger Petstore - OpenAPI 3.0",
    "description": "This is a sample Petstore Server based on the OpenAPI 3.0 specification.  You can find out more about\nSwagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!\nYou can now help us improve the API whether it's by making changes to the definition itself or to the code.\nThat way, with time, we can improve the API in general, and expose some of the new features in OAS3.\n\nSome useful links:\n- [The Petstore repository](https://github.com/swagger-api/swagger-petstore)\n- [The source API definition for the Petstore](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "x-ibm-annotations": "true",
    "x-ibm-application-name": "Example Petstore",
    "x-ibm-application-id": "petstore-example",
    "x-ibm-skill-type": "imported",
    "version": "1.0.15",
    "x-ibm-application-icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"256\" height=\"256\" preserveAspectRatio=\"xMidYMid\"><path fill=\"#85EA2D\" d=\"M127.999 249.895c-67.215 0-121.9-54.68-121.9-121.896C6.1 60.782 60.785 6.102 128 6.102c67.214 0 121.899 54.685 121.899 121.9 0 67.214-54.685 121.893-121.9 121.893Z\"/><path fill=\"#173647\" d=\"M127.999 12.202c63.954 0 115.797 51.842 115.797 115.797 0 63.952-51.843 115.797-115.797 115.797-63.952 0-115.797-51.845-115.797-115.797S64.047 12.202 127.999 12.202m0-12.202C57.419 0 0 57.42 0 127.999s57.42 127.998 127.999 127.998S256 198.577 256 128C256 57.419 198.578 0 127.999 0Z\"/><path fill=\"#173647\" d=\"M80.598 86.619c-.394 4.38.146 8.909-.146 13.338-.345 4.431-.887 8.811-1.773 13.192-1.23 6.25-5.12 10.976-10.482 14.914 10.436 6.793 11.616 17.324 12.304 28.006.345 5.76.197 11.567.788 17.276.443 4.429 2.165 5.562 6.745 5.708 1.87.048 3.786 0 5.956 0v13.683c-13.535 2.313-24.708-1.525-27.467-12.992-.887-4.184-1.478-8.467-1.673-12.798-.297-4.578.195-9.155-.148-13.732-.985-12.553-2.61-16.785-14.618-17.376v-15.602a23.714 23.714 0 0 1 2.608-.443c6.596-.345 9.4-2.364 10.828-8.86.69-3.641 1.084-7.333 1.23-11.074.494-7.136.297-14.42 1.525-21.507C67.997 68.163 74.3 63.24 84.785 62.65c2.952-.149 5.955 0 9.35 0v13.98c-1.427.1-2.658.294-3.937.294-8.515-.297-8.96 2.607-9.6 9.695Zm16.39 32.386h-.196c-4.923-.245-9.155 3.593-9.403 8.515-.246 4.972 3.592 9.206 8.515 9.45h.59c4.875.296 9.056-3.447 9.352-8.319v-.491c.1-4.971-3.886-9.055-8.857-9.155Zm30.862 0c-4.774-.148-8.763 3.593-8.909 8.318 0 .297 0 .543.051.837 0 5.365 3.641 8.812 9.155 8.812 5.414 0 8.812-3.544 8.812-9.106-.051-5.366-3.646-8.91-9.109-8.86Zm31.602 0c-5.02-.1-9.206 3.89-9.352 8.91a9.03 9.03 0 0 0 9.055 9.054h.1c4.528.788 9.106-3.592 9.402-8.858.243-4.874-4.186-9.106-9.205-9.106Zm43.363.737c-5.711-.245-8.567-2.164-9.992-7.581a54.874 54.874 0 0 1-1.624-10.582c-.395-6.596-.346-13.241-.789-19.837-1.033-15.651-12.352-21.114-28.794-18.41V76.92c2.607 0 4.626 0 6.645.049 3.495.048 6.153 1.379 6.496 5.268.345 3.543.345 7.136.69 10.73.692 7.139 1.083 14.372 2.314 21.41 1.085 5.809 5.07 10.14 10.04 13.684-8.71 5.857-11.27 14.223-11.714 23.626-.245 6.448-.394 12.944-.736 19.443-.297 5.905-2.362 7.824-8.318 7.972-1.674.05-3.298.198-5.169.297v13.93c3.495 0 6.694.196 9.892 0 9.942-.592 15.947-5.415 17.918-15.063a125.582 125.582 0 0 0 1.476-16.045c.343-4.923.297-9.894.788-14.766.737-7.63 4.232-10.78 11.862-11.27.739-.1 1.427-.246 2.118-.492v-15.604c-1.282-.149-2.17-.295-3.103-.346Z\"/></svg>"
  }

  • info:
  title: Swagger Petstore - OpenAPI 3.0
  description: >-
    This is a sample Petstore Server based on the OpenAPI 3.0 specification. 
    You can find out more about

    Swagger at [http://swagger.io](http://swagger.io). In the third iteration of
    the pet store, we've switched to the design first approach!

    You can now help us improve the API whether it's by making changes to the
    definition itself or to the code.

    That way, with time, we can improve the API in general, and expose some of
    the new features in OAS3.


    Some useful links:

    - [The Petstore repository](https://github.com/swagger-api/swagger-petstore)

    - [The source API definition for the
    Petstore](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-ibm-annotations: 'true'
  x-ibm-application-name: Example Petstore
  x-ibm-application-id: petstore-example
  x-ibm-skill-type: imported
  version: 1.0.15
  x-ibm-application-icon: >-
    <svg xmlns="http://www.w3.org/2000/svg" width="256" height="256"
    preserveAspectRatio="xMidYMid"><path fill="#85EA2D" d="M127.999
    249.895c-67.215 0-121.9-54.68-121.9-121.896C6.1 60.782 60.785 6.102 128
    6.102c67.214 0 121.899 54.685 121.899 121.9 0 67.214-54.685 121.893-121.9
    121.893Z"/><path fill="#173647" d="M127.999 12.202c63.954 0 115.797 51.842
    115.797 115.797 0 63.952-51.843 115.797-115.797 115.797-63.952
    0-115.797-51.845-115.797-115.797S64.047 12.202 127.999
    12.202m0-12.202C57.419 0 0 57.42 0 127.999s57.42 127.998 127.999 127.998S256
    198.577 256 128C256 57.419 198.578 0 127.999 0Z"/><path fill="#173647"
    d="M80.598 86.619c-.394 4.38.146 8.909-.146 13.338-.345 4.431-.887
    8.811-1.773 13.192-1.23 6.25-5.12 10.976-10.482 14.914 10.436 6.793 11.616
    17.324 12.304 28.006.345 5.76.197 11.567.788 17.276.443 4.429 2.165 5.562
    6.745 5.708 1.87.048 3.786 0 5.956 0v13.683c-13.535
    2.313-24.708-1.525-27.467-12.992-.887-4.184-1.478-8.467-1.673-12.798-.297-4.578.195-9.155-.148-13.732-.985-12.553-2.61-16.785-14.618-17.376v-15.602a23.714
    23.714 0 0 1 2.608-.443c6.596-.345 9.4-2.364 10.828-8.86.69-3.641
    1.084-7.333 1.23-11.074.494-7.136.297-14.42 1.525-21.507C67.997 68.163 74.3
    63.24 84.785 62.65c2.952-.149 5.955 0 9.35
    0v13.98c-1.427.1-2.658.294-3.937.294-8.515-.297-8.96 2.607-9.6 9.695Zm16.39
    32.386h-.196c-4.923-.245-9.155 3.593-9.403 8.515-.246 4.972 3.592 9.206
    8.515 9.45h.59c4.875.296 9.056-3.447
    9.352-8.319v-.491c.1-4.971-3.886-9.055-8.857-9.155Zm30.862
    0c-4.774-.148-8.763 3.593-8.909 8.318 0 .297 0 .543.051.837 0 5.365 3.641
    8.812 9.155 8.812 5.414 0 8.812-3.544
    8.812-9.106-.051-5.366-3.646-8.91-9.109-8.86Zm31.602 0c-5.02-.1-9.206
    3.89-9.352 8.91a9.03 9.03 0 0 0 9.055 9.054h.1c4.528.788 9.106-3.592
    9.402-8.858.243-4.874-4.186-9.106-9.205-9.106Zm43.363.737c-5.711-.245-8.567-2.164-9.992-7.581a54.874
    54.874 0 0
    1-1.624-10.582c-.395-6.596-.346-13.241-.789-19.837-1.033-15.651-12.352-21.114-28.794-18.41V76.92c2.607
    0 4.626 0 6.645.049 3.495.048 6.153 1.379 6.496 5.268.345 3.543.345 7.136.69
    10.73.692 7.139 1.083 14.372 2.314 21.41 1.085 5.809 5.07 10.14 10.04
    13.684-8.71 5.857-11.27 14.223-11.714 23.626-.245 6.448-.394 12.944-.736
    19.443-.297 5.905-2.362 7.824-8.318
    7.972-1.674.05-3.298.198-5.169.297v13.93c3.495 0 6.694.196 9.892 0
    9.942-.592 15.947-5.415 17.918-15.063a125.582 125.582 0 0 0
    1.476-16.045c.343-4.923.297-9.894.788-14.766.737-7.63 4.232-10.78
    11.862-11.27.739-.1 1.427-.246
    2.118-.492v-15.604c-1.282-.149-2.17-.295-3.103-.346Z"/></svg>

Uygulamanızın özelleştirmesini geliştirmek için info nesnesindeki x-ibm özelliklerini kullanın. Bkz. x-ibm özelliklerini kullanma.

API sunucularının yapılandırılması

Hedef sunucuya bağlanırlık bilgileri sağlamak için API uç noktasıyla API sunucularını yapılandırın. API sunucularını servers nesnesini kullanarak yapılandırırsınız.

servers nesnesi, ayarlamanız gereken her dizi öğesi için bir dizidir:

Eğilim Zorunlu Açıklama
url evet Hedef anasistemin URL 'si, bu özellik {brackets}içinde değişkeni destekler.

Aşağıdaki örnekte, https://petstore3.swagger.io/api/v3 API sunucusunu yapılandırmak için servers nesnesinin nasıl kullanılacağı gösterilmektedir.

  • "servers": [
    {
      "url": "https://petstore3.swagger.io/api/v3"
    }
  ]

  • servers:
  - url: https://petstore3.swagger.io/api/v3

Becerilerin yapılandırılması

Becerileri paths nesnesini kullanarak yapılandırabilirsiniz. paths nesnesi, tek tek uç noktalarına ve bunların işlemlerine ilişkin göreli yolları yapılandırır. Yapılandırılan her /path yöntemi, Watson Orchestra 'da beceri olarak dönüştürülür.

Becerinizi Watson Orchestrate ile yapılandırmak için OAS ' ınızda yalnızca desteklenen GET, PUT, POST ya da DELETE işlemlerini kullanmanız gerekir.

Yapılandırma, kullandığınız API ' ye bağlıdır. Aşağıdaki tablo, becerinizi yapılandırmak için kullanabileceğiniz özellikleri göstermektedir.

Özellik Zorunlu Açıklama
requestBody evet Bu beceri için geçerli istek gövdesi. Bu özellik yalnızca istek gövdeleri için tanımlanmış anlambilim içeren HTTP/1.1 belirtimini destekler.
yanıtlar evet Beceri kullanımı için beklenen HTTP yanıtları. Kullanıcıya daha iyi bir yanıt vermek için herhangi bir HTTP yanıt kodunu eşleyebilirsiniz. Eşlenen yanıtlar, beceriyi kullandıktan sonra Watson Orkestrasında görüntülenir. Kullanıcıya daha iyi yanıt vermek için en iyi uygulamaları kullanın, bkz. Beceri çıkışı.
özet hayır Watson Orkestrasında beceri adı, bu ad beceri döşemesi üzerinde görüntülenir.

Beceri özetini yapılandırma

Becerilerinize daha iyi adlar vermek için en iyi uygulamaları kullanın, bkz. Beceri adı.
açıklama hayır Watson Orchestrate ile ilgili beceri tanımı, bu açıklama beceri döşemesi üzerinde görüntülenir.

Beceri açıklamasını yapılandırma
dönüştür hayır Beceriye eklenebilecek etiketlerin listesi.
externalDocs hayır Becerinin dış belgelerine başvurma.
operationId hayır Watson Orchestrate ile ilgili benzersiz beceri tanıtıcısı.
parametreler hayır Beceri için geçerli parametrelerin bir listesi.
Geri Çağırmalar hayır Üst beceriyle ilgili bant dışı geri çağırmalar olabilir.
kullanım dışı bırakıldı hayır Becerinin kullanımdan kaldırılmış olduğunu bildirir.
güvenliğinde olmak üzere, hayır Beceriyi kullanmak için gerekli güvenlik şemalarının listesi.
sunucular hayır Beceriyi çalıştırmak için alternatif sunucuları listeleyen bir dizi.
x-ibm özelliği hayır Watson Orchestra 'ya beceriyle ilgili daha fazla bilgi eklemek için kullanabileceğiniz x-ibm özellikleri. Bkz. x-ibm özelliklerini kullanma.

Aşağıdaki örnek, becerileri yapılandırmak için paths nesnesinin nasıl kullanılacağını göstermektedir.

  • "paths": {
  "/pet": {
    "put": {
      "tags": [
        "pet"
      ],
      "summary": "Update an existing pet",
      "description": "Update an existing pet by Id",
      "operationId": "updatePet",
      "requestBody": {
        "description": "Update an existent pet in the store",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          },
          "application/xml": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          },
          "application/x-www-form-urlencoded": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          }
        },
        "required": true
      },
      "x-ibm-ui-extension": {
        "component": "dropdown",
        "actions": [
          {
            "skill_id": "<skill_id where it is refering from>",
            "type": "data",
            "params": {}
          }
        ]
      },
      "responses": {
        "200": {
          "description": "Successful operation",
          "content": {
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        },
        "400": {
          "description": "Bad Request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Errors"
              }
            }
          }
        },
        "401": {
          "description": "Unauthorized",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Errors"
              }
            }
          }
        }
      }
    },
    "post": {
      "tags": [
        "pet"
      ],
      "summary": "Add a new pet to the store",
      "description": "Add a new pet to the store",
      "operationId": "addPet",
      "requestBody": {
        "description": "Create a new pet in the store",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          },
          "application/xml": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          },
          "application/x-www-form-urlencoded": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          }
        },
        "required": true
      },
      "responses": {
        "200": {
          "description": "Successful operation",
          "content": {
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        },
        "405": {
          "description": "Invalid input"
        }
      }
    }
  },
  "/pet/findByStatus": {
    "get": {
      "tags": [
        "pet"
      ],
      "summary": "Finds Pets by status",
      "description": "Multiple status values can be provided with comma separated strings",
      "operationId": "findPetsByStatus",
      "x-ibm-next-actions": [
        {
          "skill_id": "email-agent",
          "utterance": "Email it"
        }
      ],
      "parameters": [
        {
          "$ref": "#/components/parameters/statusParam"
        }
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "content": {
            "application/xml": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },
        "400": {
          "description": "Invalid status value"
        }
      }
    }
  },
  "/pet/{petId}": {
    "get": {
      "tags": [
        "pet"
      ],
      "summary": "Find pet by ID",
      "description": "Returns a single pet",
      "operationId": "getPetById",
      "parameters": [
        {
          "name": "petId",
          "in": "path",
          "description": "ID of pet to return",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "content": {
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        },
        "400": {
          "description": "Invalid ID supplied"
        },
        "404": {
          "description": "Pet not found"
        }
      }
    },
    "post": {
      "tags": [
        "pet"
      ],
      "summary": "Updates a pet in the store with form data",
      "description": "",
      "operationId": "updatePetWithForm",
      "parameters": [
        {
          "name": "petId",
          "in": "path",
          "description": "ID of pet that needs to be updated",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        },
        {
          "name": "name",
          "in": "query",
          "description": "Name of pet that needs to be updated",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "status",
          "in": "query",
          "description": "Status of pet that needs to be updated",
          "schema": {
            "type": "string"
          }
        }
      ],
      "responses": {
        "405": {
          "description": "Invalid input"
        }
      }
    },
    "delete": {
      "tags": [
        "pet"
      ],
      "summary": "Deletes a pet",
      "description": "",
      "operationId": "deletePet",
      "x-ibm-show": "true",
      "parameters": [
        {
          "name": "api_key",
          "in": "header",
          "description": "",
          "required": false,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "petId",
          "in": "path",
          "description": "Pet id to delete",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ],
      "responses": {
        "400": {
          "description": "Invalid pet value"
        }
      }
    }
  },
  "/store/order": {
    "post": {
      "tags": [
        "store"
      ],
      "summary": "Place an order for a pet",
      "description": "Place a new order in the store",
      "operationId": "placeOrder",
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "application/xml": {
            "schema": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "application/x-www-form-urlencoded": {
            "schema": {
              "$ref": "#/components/schemas/Order"
            }
          }
        }
      },
      "responses": {
        "200": {
          "description": "successful operation",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Order"
              }
            }
          }
        },
        "405": {
          "description": "Invalid input"
        }
      }
    }
  },
  "/store/order/{orderId}": {
    "get": {
      "tags": [
        "store"
      ],
      "summary": "Find purchase order by ID",
      "description": "For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.",
      "operationId": "getOrderById",
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "description": "ID of order that needs to be fetched",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "content": {
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/Order"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Order"
              }
            }
          }
        },
        "400": {
          "description": "Invalid ID supplied"
        },
        "404": {
          "description": "Order not found"
        }
      }
    },
    "delete": {
      "tags": [
        "store"
      ],
      "summary": "Delete purchase order by ID",
      "description": "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors",
      "operationId": "deleteOrder",
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "description": "ID of the order that needs to be deleted",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ],
      "responses": {
        "400": {
          "description": "Invalid ID supplied"
        },
        "404": {
          "description": "Order not found"
        }
      }
    }
  },
  "/user/login": {
    "get": {
      "tags": [
        "user"
      ],
      "summary": "Logs user into the system",
      "description": "",
      "operationId": "loginUser",
      "parameters": [
        {
          "name": "username",
          "in": "query",
          "description": "The user name for login",
          "required": false,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "password",
          "in": "query",
          "description": "The password for login in clear text",
          "required": false,
          "schema": {
            "type": "string"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "headers": {
            "X-Rate-Limit": {
              "description": "calls per hour allowed by the user",
              "schema": {
                "type": "integer",
                "format": "int32"
              }
            },
            "X-Expires-After": {
              "description": "date in UTC when token expires",
              "schema": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "content": {
            "application/xml": {
              "schema": {
                "type": "string"
              }
            },
            "application/json": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "400": {
          "description": "Invalid username/password supplied"
        }
      }
    }
  },
  "/user/logout": {
    "get": {
      "tags": [
        "user"
      ],
      "summary": "Logs out current logged in user session",
      "description": "",
      "operationId": "logoutUser",
      "parameters": [],
      "responses": {
        "default": {
          "description": "successful operation"
        }
      }
    }
  }
}

  • paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      operationId: updatePet
      requestBody:
        description: Update an existent pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      x-ibm-ui-extension:
        component: dropdown
        actions:
          - skill_id: <skill_id where it is refering from>
            type: data
            params: {}
      responses:
        '200':
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '405':
          description: Invalid input
  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      x-ibm-next-actions:
        - skill_id: email-agent
          utterance: Email it
      parameters:
        - $ref: '#/components/parameters/statusParam'
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value
  /pet/{petId}:
    get:
      tags:
        - pet
      summary: Find pet by ID
      description: Returns a single pet
      operationId: getPetById
      parameters:
        - name: petId
          in: path
          description: ID of pet to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
    post:
      tags:
        - pet
      summary: Updates a pet in the store with form data
      description: ''
      operationId: updatePetWithForm
      parameters:
        - name: petId
          in: path
          description: ID of pet that needs to be updated
          required: true
          schema:
            type: integer
            format: int64
        - name: name
          in: query
          description: Name of pet that needs to be updated
          schema:
            type: string
        - name: status
          in: query
          description: Status of pet that needs to be updated
          schema:
            type: string
      responses:
        '405':
          description: Invalid input
    delete:
      tags:
        - pet
      summary: Deletes a pet
      description: ''
      operationId: deletePet
      x-ibm-show: 'true'
      parameters:
        - name: api_key
          in: header
          description: ''
          required: false
          schema:
            type: string
        - name: petId
          in: path
          description: Pet id to delete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '400':
          description: Invalid pet value
  /store/order:
    post:
      tags:
        - store
      summary: Place an order for a pet
      description: Place a new order in the store
      operationId: placeOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
          application/xml:
            schema:
              $ref: '#/components/schemas/Order'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '405':
          description: Invalid input
  /store/order/{orderId}:
    get:
      tags:
        - store
      summary: Find purchase order by ID
      description: >-
        For valid response try integer IDs with value <= 5 or > 10. Other values
        will generate exceptions.
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          description: ID of order that needs to be fetched
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Order'
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':##
          description: Invalid ID supplied
        '404':
          description: Order not found
    delete:
      tags:
        - store
      summary: Delete purchase order by ID
      description: >-
        For valid response try integer IDs with value < 1000. Anything above
        1000 or nonintegers will generate API errors
      operationId: deleteOrder
      parameters:
        - name: orderId
          in: path
          description: ID of the order that needs to be deleted
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '400':
          description: Invalid ID supplied
        '404':
          description: Order not found
  /user/login:
    get:
      tags:
        - user
      summary: Logs user into the system
      description: ''
      operationId: loginUser
      parameters:
        - name: username
          in: query
          description: The user name for login
          required: false
          schema:
            type: string
        - name: password
          in: query
          description: The password for login in clear text
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          headers:
            X-Rate-Limit:
              description: calls per hour allowed by the user
              schema:
                type: integer
                format: int32
            X-Expires-After:
              description: date in UTC when token expires
              schema:
                type: string
                format: date-time
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: string
        '400':
          description: Invalid username/password supplied
  /user/logout:
    get:
      tags:
        - user
      summary: Logs out current logged in user session
      description: ''
      operationId: logoutUser
      parameters: []
      responses:
        default:
          description: successful operation

API güvenlik şemasını yapılandırma

componentsüzerinde securitySchemes özelliğinde API bağlantısını yapılandırırsınız. securitySchemesiçinde yalnızca bir bağlantı yapılandırın, bu bağlantı Watson Orchestra 'da uygulamayı bağlamak için kullanılır.

Aşağıdaki tabloda, Watson Orchestra 'da kullanabileceğiniz desteklenen kimlik doğrulama şemalarına ilişkin ayrıntılar sağlanır.

Durum Açıklama
Desteklenen kimlik doğrulama şemaları -Temel
-Ayıran
-İstemci kimlik doğrulaması ve OAuth2 istemci kimlik bilgileri akışı da içinde olmak üzere OAuth2 parola akışı.

Not: Belirtik refreshUrl desteklenmez. Erişim simgesi yanıtı bir refresh_tokeniçeriyorsa, refreshUrl öğesinin tokenUrlile aynı olduğu varsayılır. Bu nedenle, refreshUrl davranışı etkilemez.


-Üstbilgide API anahtarı
-Sorgu parametresi
-Tanımlama Bilgisi

Not: Tanımlama bilgisi için, değerin bağlantı sırasında yapılandırılması gerekir.
Desteklenmeyen kimlik doğrulama şemaları -RFC 7325 http şeması desteği
-Özet, HOBA, karşılıklı, OAuth 1.0, anlaşma, SCRAM-SHA-1, SCRAM-SHA-256, VAPID desteği
-Tanımlama bilgisi kimlik doğrulaması
-OIDC.

Aşağıdaki örneklerde, kimlik doğrulamaları yapılandırmak için securitySchemes özelliğinin nasıl kullanılacağı gösterilmiştir.

  • Temel kimlik doğrulama örneği.

    "components": {
  "securitySchemes": {
    "basic_auth": {
      "type": "http",
      "scheme": "basic"
    }
  }
}

    Taşıyıcı kimlik doğrulaması örneği.

    "components": {
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  }
}

    API anahtarı kimlik doğrulaması örneği.

    "components": {
  "securitySchemes": {
    "bearerAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization"
    }
  }
}

    OAuth2 kimlik doğrulaması örneği.

    "components": {
  "securitySchemes": {
    "passwordGrant": {
      "type": "oauth2",
      "description": "Password grant authorization.",
      "flows": {
        "password": {
          "tokenUrl": "https://api.example.com/oauth2/authorize",
          "scopes": {}
        }
      }
    }
  }
}

    Watson Orchestra 'da OAuth 2.0 örtük izin akışı kullanılabilir. Örtük akışta, OAuth sağlayıcıları oturum açma sayfasında bir beceriyi çalıştırmak için kimlik doğrulamasını bulabilirsiniz. Daha fazla bilgi için bkz. OAuth örtük izin akışı.

    "components": {
  "securitySchemes": {
    "oAuthSample": {
      "type": "oauth2",
      "description": "This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://api.example.com/oauth2/authorize",
          "scopes": {
            "read_pets": "read your pets",
            "write_pets": "modify pets in your account"
          }
        }
      }
    }
  }
}

  • Temel kimlik doğrulama örneği.

    components:
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic

    Taşıyıcı kimlik doğrulaması örneği.

    components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

    API anahtarı kimlik doğrulaması örneği.

    components:
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization

    OAuth2 kimlik doğrulaması örneği.

    components:
  securitySchemes:
    passwordGrant:
      type: oauth2
      description: Password grant authorization.
      flows:
        password:
          tokenUrl: https://api.example.com/oauth2/authorize
          scopes: {}

    Watson Orchestra 'da OAuth 2.0 örtük izin akışı kullanılabilir. Örtük akışta, OAuth sağlayıcıları oturum açma sayfasında bir beceriyi çalıştırmak için kimlik doğrulamasını bulabilirsiniz. Daha fazla bilgi için bkz. OAuth örtük izin akışı.

    components:
  securitySchemes:
    oAuthSample:    # <---- arbitrary name
      type: oauth2
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
      flows:
        implicit:   # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
          authorizationUrl: https://api.example.com/oauth2/authorize
          scopes:
            read_pets: read your pets
            write_pets: modify pets in your account

Becerileri kullanmak için kimlik doğrulaması gerekiyorsa, bunu security nesnesinde yapılandırmanız gerekir.

Bir kimlik doğrulamasını gerektiği gibi yapılandırmak için securitySchemesiçinde ayarladığınız adı kullanmanız gerekir. Aşağıdaki örneklerde, önceki kimlik doğrulama örneklerinin gerektiği şekilde nasıl yapılandırılacağı gösterilmiştir.

  • Temel kimlik doğrulama örneği.

    "security": [
  {
    "basic_auth": []
  }
]

    Taşıyıcı kimlik doğrulaması örneği.

    "security": [
  {
    "bearerAuth": []
  }
]

    Taşıyıcı kimlik doğrulaması örneği.

    "security": [
  {
    "bearerAuth": []
  }
]

    OAuth2 kimlik doğrulaması örneği.

    "security": [
  {
    "passwordGrant": []
  }
]

    OAuth2 örtük kimlik doğrulaması örneği.

    "security": [
  {
    "oAuthSample": []
  }
]

  • Temel kimlik doğrulama örneği.

    security:
  - basic_auth: [ ]

    API anahtarı kimlik doğrulaması örneği.

    security:
  - bearerAuth: [ ]

    API anahtarı kimlik doğrulaması örneği.

    security:
  - bearerAuth: [ ]

    OAuth2 kimlik doğrulaması örneği.

    security:
  - passwordGrant: [ ]

    OAuth2 örtük kimlik doğrulaması örneği.

    security:
  - oAuthSample: [ ]

İsteğe bağlı: Yeniden kullanılabilir nesnelerin yapılandırılması

Farklı beceriler, aynı istek ya da yanıt yapısına sahip olabilir. Yapıyı bir kez yapılandırabilir ve sonra bu yapıyı kullanan her beceriye başvurabilirsiniz.

components nesnesinde yeniden kullanılabilir nesneleri yapılandırabilirsiniz; bu nesnede schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacksve x-ibm properties , gerektiğinde OAS içinde yeniden kullanılmak üzere yapılandırılabilir.

Aşağıdaki örnekte, yeniden kullanılabilir parameters, schemasve requestBodies' yi yapılandırmak için components nesnesinin nasıl kullanılacağı gösterilmektedir.

  • "components": {
  "parameters": {
    "statusParam": {
      "in": "query",
      "name": "status",
      "description": "Status values that need to be considered for filter",
      "required": false,
      "explode": true,
      "x-ibm-ui-extension": {
        "component": "dropdown",
        "actions": [
          {
            "skill_id": "status1.0.0",
            "type": "data",
            "params": null
          }
        ]
      },
      "schema": {
        "default": "available",
        "type": "string",
        "enum": [
          "available",
          "pending",
          "sold"
        ]
      }
    }
  },
  "schemas": {
    "Errors": {
      "type": "object",
      "description": "The Error object contains errors array that lists all of the errors that have occurred",
      "required": [
        "errors"
      ],
      "properties": {
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ErrorItem"
          }
        }
      }
    },
    "ErrorItem": {
      "description": "Each error must have a code and a message",
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": true,
      "properties": {
        "code": {
          "description": "Error Code",
          "type": "string"
        },
        "message": {
          "description": "Human readable message for this error",
          "type": "string"
        }
      }
    },
    "Order": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "example": 10
        },
        "petId": {
          "type": "integer",
          "format": "int64",
          "example": 198772
        },
        "quantity": {
          "type": "integer",
          "format": "int32",
          "example": 7
        },
        "shipDate": {
          "type": "string",
          "format": "date-time"
        },
        "status": {
          "type": "string",
          "description": "Order Status",
          "example": "approved",
          "enum": [
            "placed",
            "approved",
            "delivered"
          ]
        },
        "complete": {
          "type": "boolean"
        }
      },
      "xml": {
        "name": "order"
      }
    },
    "Customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "example": 100000
        },
        "username": {
          "type": "string",
          "example": "fehguy"
        },
        "address": {
          "type": "array",
          "xml": {
            "name": "addresses",
            "wrapped": true
          },
          "items": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "xml": {
        "name": "customer"
      }
    },
    "Address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string",
          "example": "437 Lytton"
        },
        "city": {
          "type": "string",
          "example": "Palo Alto"
        },
        "state": {
          "type": "string",
          "example": "CA"
        },
        "zip": {
          "type": "string",
          "example": "94301"
        }
      },
      "xml": {
        "name": "address"
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "example": 1
        },
        "name": {
          "type": "string",
          "example": "Dogs"
        }
      },
      "xml": {
        "name": "category"
      }
    },
    "User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "example": 10
        },
        "username": {
          "type": "string",
          "example": "theUser"
        },
        "firstName": {
          "type": "string",
          "example": "John"
        },
        "lastName": {
          "type": "string",
          "example": "James"
        },
        "email": {
          "type": "string",
          "example": "john@email.com"
        },
        "password": {
          "type": "string",
          "example": "12345"
        },
        "phone": {
          "type": "string",
          "example": "12345"
        },
        "userStatus": {
          "type": "integer",
          "description": "User Status",
          "format": "int32",
          "example": 1
        }
      },
      "xml": {
        "name": "user"
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      },
      "xml": {
        "name": "tag"
      }
    },
    "Pet": {
      "required": [
        "name",
        "photoUrls"
      ],
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "example": 10
        },
        "name": {
          "type": "string",
          "example": "doggie"
        },
        "category": {
          "$ref": "#/components/schemas/Category"
        },
        "photoUrls": {
          "type": "array",
          "xml": {
            "wrapped": true
          },
          "items": {
            "type": "string",
            "xml": {
              "name": "photoUrl"
            }
          }
        },
        "tags": {
          "type": "array",
          "xml": {
            "wrapped": true
          },
          "items": {
            "$ref": "#/components/schemas/Tag"
          }
        },
        "status": {
          "type": "string",
          "description": "pet status in the store",
          "enum": [
            "available",
            "pending",
            "sold"
          ]
        }
      },
      "xml": {
        "name": "pet"
      }
    },
    "ApiResponse": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "type": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "xml": {
        "name": "##default"
      }
    }
  },
  "requestBodies": {
    "Pet": {
      "description": "Pet object that needs to be added to the store",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Pet"
          }
        },
        "application/xml": {
          "schema": {
            "$ref": "#/components/schemas/Pet"
          }
        }
      }
    },
    "UserArray": {
      "description": "List of user object",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      }
    }
  }
}

  • components:
  parameters:
    statusParam:
      in: query
      name: status
      description: Status values that need to be considered for filter
      required: false
      explode: true
      x-ibm-ui-extension:
        component: dropdown
        actions:
          - skill_id: status1.0.0
            type: data
            params: null
      schema:
        default: available
        type: string
        enum:
          - available
          - pending
          - sold
  schemas:
    Errors:
      type: object
      description: >-
        The Error object contains errors array that lists all of the errors that
        have occurred
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
    ErrorItem:
      description: Each error must have a code and a message
      type: object
      required:
        - code
        - message
      additionalProperties: true
      properties:
        code:
          description: Error Code
          type: string
        message:
          description: Human readable message for this error
          type: string
    Order:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        petId:
          type: integer
          format: int64
          example: 198772
        quantity:
          type: integer
          format: int32
          example: 7
        shipDate:
          type: string
          format: date-time
        status:
          type: string
          description: Order Status
          example: approved
          enum:
            - placed
            - approved
            - delivered
        complete:
          type: boolean
      xml:
        name: order
    Customer:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 100000
        username:
          type: string
          example: fehguy
        address:
          type: array
          xml:
            name: addresses
            wrapped: true
          items:
            $ref: '#/components/schemas/Address'
      xml:
        name: customer
    Address:
      type: object
      properties:
        street:
          type: string
          example: 437 Lytton
        city:
          type: string
          example: Palo Alto
        state:
          type: string
          example: CA
        zip:
          type: string
          example: '94301'
      xml:
        name: address
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: category
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        username:
          type: string
          example: theUser
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: James
        email:
          type: string
          example: john@email.com
        password:
          type: string
          example: '12345'
        phone:
          type: string
          example: '12345'
        userStatus:
          type: integer
          description: User Status
          format: int32
          example: 1
      xml:
        name: user
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: tag
    Pet:
      required:
        - name
        - photoUrls
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        tags:
          type: array
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
      xml:
        name: pet
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        type:
          type: string
        message:
          type: string
      xml:
        name: '##default'
  requestBodies:
    Pet:
      description: Pet object that needs to be added to the store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'
        application/xml:
          schema:
            $ref: '#/components/schemas/Pet'
    UserArray:
      description: List of user object
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User'

Yeniden kullanılabilir bir nesne kullanmak için $ref özelliğini kullanın ve yolu yeniden kullanılabilir nesneye geçirin.

Aşağıdaki örnekte, yanıt şemasını yapılandırmak için önceki örnekte yapılandırılan Order yeniden kullanılabilir nesnesinin nasıl kullanılacağı gösterilmektedir.

  • "responses": {
  "200": {
    "description": "successful operation",
    "content": {
      "application/xml": {
        "schema": {
          "$ref": "#/components/schemas/Order"
        }
      },
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Order"
        }
      }
    }
  },
  "400": {
    "description": "Invalid ID supplied"
  },
  "404": {
    "description": "Order not found"
  }
}

  • responses:
  '200':
    description: successful operation
    content:
      application/xml:
        schema:
          "$ref": "#/components/schemas/Order"
      application/json:
        schema:
          "$ref": "#/components/schemas/Order"
  '400':
    description: Invalid ID supplied
  '404':
    description: Order not found