Tworzenie specyfikacji OpenAPI

Kwalifikacje można importować z plików specyfikacji OpenAPI Specification (OAS). Plik OAS jest przekształcany w aplikację i umiejętności w systemie Watson Orchestrate. W tym dokumencie wyjaśniono, w jaki sposób można utworzyć usługę OAS w celu zaimportowania do programu Watson Orchestrate.

Zanim rozpoczniesz

  • Użytkownik musi mieć dostęp do programu budującego w systemie Watson Orchestrate.
  • Potrzebny jest jeden edytor plików tekstowych, który obsługuje formaty YAML lub JSON.

Konfigurowanie wersji OpenAPI

Ustaw wersję używaną w serwerze OAS do importowania do programu Watson Orchestrate. Wersję można ustawić za pomocą obiektu openapi .

Aby serwer OAS mógł zostać zaimportowany do programu Watson Orchestrate, należy użyć wersji 3.x lub nowszej.

Poniższy przykład przedstawia sposób użycia obiektu openapi do ustawienia wersji 3.0.2 OAS.

  • "openapi": "3.0.2"

  • openapi: 3.0.2

Konfigurowanie aplikacji

Aplikację kwalifikacji można skonfigurować za pomocą obiektu info . Obiekt info udostępnia metadane OAS. Metadane są używane do tworzenia aplikacji na platformie Watson Orchestrate.

W poniższej tabeli opisano właściwości, które są używane do tworzenia aplikacji w systemie Watson Orchestrate.

Proprety Wymagane Opis
tytuł tak Definiuje tytuł aplikacji. Ta właściwość definiuje również nazwę aplikacji w systemie Watson Orchestrate, jeśli nie ustawiono właściwości x-ibm-application-name .

Konfigurowanie tytułu aplikacji
Opis nie Definiuje opis aplikacji.
wersja tak Definiuje wersję aplikacji.

Poniższy przykład przedstawia sposób użycia obiektu info do skonfigurowania aplikacji Pet shot .

  • "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>

Użyj właściwości x-ibm w obiekcie info , aby poprawić dostosowanie aplikacji. Patrz Korzystanie z właściwości x-ibm.

Konfigurowanie serwerów API

Skonfiguruj serwery API z punktem końcowym interfejsu API, aby udostępnić informacje o połączeniach dla serwera docelowego. Serwery API konfiguruje się za pomocą obiektu servers .

Obiekt servers jest tablicą, którą należy ustawić dla każdego elementu tablicy:

Proprety Wymagane Opis
url tak Adres URL hosta docelowego. Ta właściwość obsługuje zmienną w {brackets}.

Poniższy przykład przedstawia sposób użycia obiektu servers do skonfigurowania serwera API https://petstore3.swagger.io/api/v3 .

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

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

Konfigurowanie kwalifikacji

Umiejętności konfiguruje się za pomocą obiektu paths . Obiekt paths konfiguruje ścieżki względne do poszczególnych punktów końcowych i ich operacje. Każda skonfigurowana metoda /path jest przekształcana w umiejętność w systemie Watson Orchestrate.

Aby skonfigurować swoje umiejętności w programie Watson Orchestrate, należy używać tylko obsługiwanych operacji GET, PUT, POST lub DELETE w OAS.

Konfiguracja zależy od używanego interfejsu API. W poniższej tabeli przedstawiono właściwości, których można użyć do skonfigurowania kwalifikacji.

Właściwość Wymagane Opis
requestBody tak Treść żądania mająca zastosowanie do tej umiejętności. Ta właściwość obsługuje tylko specyfikację HTTP/1.1 ze zdefiniowaną semantyką dla treści żądań.
odpowiedzi tak Oczekiwane odpowiedzi HTTP dla wykorzystania umiejętności. Można odwzorować dowolny kod odpowiedzi HTTP, aby uzyskać lepszą odpowiedź dla użytkownika. Odwzorowane odpowiedzi są wyświetlane w programie Watson Orchestrate po użyciu kwalifikacji. Skorzystaj ze sprawdzonych procedur, aby udzielić użytkownikowi lepszych odpowiedzi, patrz sekcja Dane wyjściowe umiejętności.
Podsumowanie nie Nazwa umiejętności w systemie Watson Orchestrate jest wyświetlana na kaflu umiejętności.

Konfigurowanie podsumowania kwalifikacji

Użyj sprawdzonych procedur, aby nadać swoim umiejętnościom lepsze nazwy (patrz sekcja Nazwa umiejętności).
Opis nie Opis umiejętności w systemie Watson Orchestrate, ten opis jest wyświetlany na kaflu umiejętności.

Konfigurowanie opisu kwalifikacji
znaczniki nie Lista znaczników, które można dodać do umiejętności.
externalDocs nie Odsyłanie do zewnętrznej dokumentacji umiejętności.
operationId nie Unikalny identyfikator umiejętności w systemie Watson Orchestrate.
Parametry nie Lista parametrów, które mają zastosowanie do kwalifikacji.
Wywołania zwrotne nie Możliwe wywołania zwrotne poza grupą, które są powiązane z umiejętnością nadrzędną.
nieaktualne nie Deklaruje, że kwalifikacja jest nieaktualna.
punktów końcowych nie Lista schematów zabezpieczeń wymaganych do użycia kwalifikacji.
w chmurze nie Tablica zawierająca listę alternatywnych serwerów, które mają uruchomić tę umiejętność.
Właściwość x-ibm nie Właściwości x-ibm, których można użyć, aby dodać więcej informacji o umiejętnościach do programu Watson Orchestrate. Patrz Korzystanie z właściwości x-ibm.

W poniższym przykładzie przedstawiono sposób użycia obiektu paths do skonfigurowania kwalifikacji.

  • "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

Konfigurowanie schematu zabezpieczeń interfejsu API

Połączenie interfejsu API można skonfigurować we właściwości securitySchemes w systemie components. Skonfiguruj tylko jedno połączenie w programie securitySchemes. To połączenie jest używane do nawiązania połączenia z aplikacją Watson Orchestrate.

Poniższa tabela zawiera szczegółowe informacje o obsługiwanych schematach uwierzytelniania, których można używać w systemie Watson Orchestrate.

Status Opis
Obsługiwane schematy uwierzytelniania -Podstawowy
-Bearer
-przepływ hasła OAuth2 , w tym uwierzytelnianie klienta, a także przepływ referencji klienta OAuth2 .

Uwaga: opcja Jawne refreshUrl nie jest obsługiwana. Jeśli odpowiedź tokenu dostępu zawiera refresh_token, zakłada się, że refreshUrl jest taki sam jak tokenUrl. Dlatego refreshUrl nie ma wpływu na zachowanie.


-Klucz API w nagłówku
-Parametr zapytania
-Cookie

Uwaga: W przypadku informacji cookie wartość musi być skonfigurowana w czasie połączenia.
Nieobsługiwane schematy uwierzytelniania -Obsługa schematu HTTP RFC 7325
-Digest, HOBA, Mutual, OAuth 1.0, negotiate, SCRAM-SHA-1, SCRAM-SHA-256, obsługa VAPID
-Uwierzytelnianie informacji cookie
-OIDC.

W poniższych przykładach przedstawiono sposób użycia właściwości securitySchemes do skonfigurowania uwierzytelniania.

  • Przykład uwierzytelniania podstawowego.

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

    Przykład uwierzytelniania na okaziciela.

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

    Przykład uwierzytelniania za pomocą klucza API.

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

    Przykład uwierzytelniania OAuth2 .

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

    W programie Watson Orchestrate można użyć OAuth 2.0 niejawnego przepływu nadawania. W przepływie niejawnym można znaleźć uwierzytelnianie, aby uruchomić umiejętność na stronie logowania dostawców OAuth. Więcej informacji na ten temat zawiera sekcja Przepływ nadania niejawnego OAuth.

    "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"
          }
        }
      }
    }
  }
}

  • Przykład uwierzytelniania podstawowego.

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

    Przykład uwierzytelniania na okaziciela.

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

    Przykład uwierzytelniania za pomocą klucza API.

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

    Przykład uwierzytelniania OAuth2 .

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

    W programie Watson Orchestrate można użyć OAuth 2.0 niejawnego przepływu nadawania. W przepływie niejawnym można znaleźć uwierzytelnianie, aby uruchomić umiejętność na stronie logowania dostawców OAuth. Więcej informacji na ten temat zawiera sekcja Przepływ nadania niejawnego OAuth.

    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

Jeśli do korzystania z kwalifikacji wymagane jest uwierzytelnianie, należy je skonfigurować w obiekcie security .

Aby skonfigurować jedno uwierzytelnianie zgodnie z wymaganiami, należy użyć tej samej nazwy, która została ustawiona w sekcji securitySchemes. W poniższych przykładach przedstawiono sposób konfigurowania wcześniejszych przykładów uwierzytelniania zgodnie z wymaganiami.

  • Przykład uwierzytelniania podstawowego.

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

    Przykład uwierzytelniania na okaziciela.

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

    Przykład uwierzytelniania na okaziciela.

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

    Przykład uwierzytelniania OAuth2 .

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

    Przykład niejawnego uwierzytelniania OAuth2 .

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

  • Przykład uwierzytelniania podstawowego.

    security:
  - basic_auth: [ ]

    Przykład uwierzytelniania za pomocą klucza API.

    security:
  - bearerAuth: [ ]

    Przykład uwierzytelniania za pomocą klucza API.

    security:
  - bearerAuth: [ ]

    Przykład uwierzytelniania OAuth2 .

    security:
  - passwordGrant: [ ]

    Przykład niejawnego uwierzytelniania OAuth2 .

    security:
  - oAuthSample: [ ]

Opcjonalnie: konfigurowanie obiektów wielokrotnego użytku

Różne umiejętności mogą mieć taką samą strukturę żądań lub odpowiedzi. Strukturę można skonfigurować raz, a następnie odwołać się do każdej umiejętności, która korzysta z tej struktury.

Można skonfigurować obiekty wielokrotnego użytku w obiekcie components , w tym obiekcie można skonfigurować schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacksi x-ibm properties do ponownego wykorzystania w razie potrzeby w OAS.

Poniższy przykład przedstawia sposób użycia obiektu components do skonfigurowania obiektów parameters, schemasi requestBodieswielokrotnego użytku.

  • "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'

Aby użyć jednego obiektu wielokrotnego użytku, należy użyć właściwości $ref i przekazać ścieżkę do obiektu wielokrotnego użytku.

W poniższym przykładzie przedstawiono sposób użycia obiektu wielokrotnego użytku Order , który został skonfigurowany w poprzednim przykładzie, do skonfigurowania schematu odpowiedzi.

  • "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