Merge pull request #1555 from RasaHQ/action_server_spec

add OpenAPI spec for the action server

.travis.yml

@@ -28,6 +28,7 @@ jobs:
     - npm install -g swagger-cli
     script:
     - swagger-cli validate docs/_static/spec/server.yml
+    - swagger-cli validate docs/_static/spec/action_server.yml
     after_success:
     - coveralls
   - stage: integration

CHANGELOG.rst

@@ -12,6 +12,7 @@ This project adheres to `Semantic Versioning`_ starting with version 0.2.0.
 
 Added
 -----
+- open api spec for the Rasa Core SDK action server
 
 Changed
 -------

docs/_static/spec/action_server.yml

@@ -0,0 +1,128 @@
+openapi: "3.0.2"
+info:
+  title: "Rasa Core SDK - Action Server Endpoint"
+  version: "0.0.0"
+  description: >-
+    API of the action server which is used by Rasa Core 
+    to execute custom actions.
+servers:
+  - url: "http://localhost:5055/webhook"
+    description: "Local development action server"
+paths:
+  /:
+    post:
+      summary: Core request to execute a custom action
+      description: >-
+        Rasa Core sends a request to the action server to execute a
+        certain custom action. As a response to the action call from Core,
+        you can modify the tracker, e.g. by setting slots and send responses
+        back to the user.
+      operationId: call_action
+      requestBody:
+        description: >- 
+          Describes the action to be called and provides information on the 
+          current state of the conversation.
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                next_action:
+                  description: The name of the action which should be executed.
+                  type: string
+                sender_id:
+                  description: >-
+                    Unique id of the user who is having the
+                    current conversation.
+                  type: string
+                tracker:
+                  $ref: "./server.yml#/components/schemas/Tracker"
+                domain:
+                  $ref: "./server.yml#/components/schemas/Domain"
+      responses:
+        200:
+          description: Action was executed succesfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  events:
+                    description: Events returned by the action.
+                    type: array
+                    items:
+                      $ref: "./server.yml#/components/schemas/Event"
+                  responses:
+                    description: >-
+                      List of responses which should be sent to the user
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Response"
+        400:
+          description: >-
+            Action execution was rejected. This is the same as returning
+            an `ActionExecutionRejected` event.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  action_name:
+                    type: string
+                    description: >-
+                      Name of the action which rejected its execution.
+                  error:
+                    type: string
+                    description: The error message.
+        500:
+          description: >-
+            The action server encountered an exception while running the action.
+components:
+  schemas:
+    Response:
+      oneOf:
+        - $ref: '#/components/schemas/TextResponse'
+        - $ref: '#/components/schemas/TemplateResponse'
+        - $ref: '#/components/schemas/ButtonResponse'
+    TextResponse:
+      description: Text which the bot should utter.
+      type: object
+      properties:
+        text:
+          description: The text which should be uttered.
+          type: string
+      required: ["text"]
+    TemplateResponse:
+      description: Response template the bot should utter.
+      type: object
+      properties:
+        template:
+          description: Name of the template
+          type: string
+      additionalProperties:
+        description: Keyword argument to fill the template
+        type: string
+      required: ["template"]
+    ButtonResponse:
+      description: Text with buttons which should be sent to the user.
+      type: object
+      properties:
+        text:
+          type: string
+          description: Message
+        buttons:
+          type: array
+          items:
+            $ref: '#/components/schemas/Button'
+    Button:
+      description: >-
+        A button which can be clicked by the user in the conversation.
+      type: object
+      properties:
+        title:
+          type: string
+          description: The text on the button
+        payload:
+          type: string
+          description: Payload which is sent if the button is pressed.

docs/_static/spec/server.yml

@@ -1,7 +1,7 @@
 openapi: "3.0.1"
 info:
   title: "Rasa Core - Server Endpoints"
-  version: "0.12.0"
+  version: "0.0.0"
   description: >-
     The Rasa Core server provides endpoints to retrieve trackers of
     conversations as well as endpoints to modify them.
@@ -1180,6 +1180,33 @@ components:
           text:
             type: string
         required: ["event", "text"]
+    form_validation:
+      allOf:
+        - $ref: '#/components/schemas/Event'
+        - type: object
+          properties:
+            validate:
+              type: string #TODO
+    form:
+      allOf:
+        - $ref: '#/components/schemas/Event'
+        - type: object
+          properties:
+            name:
+              type: string
+    action_execution_rejected:
+      allOf:
+        - $ref: '#/components/schemas/Event'
+        - type: object
+          properties:
+            name:
+              type: string
+            policy:
+              type: string #todo
+              nullable: true
+            confidence:
+              type: float
+              nullable: true
     Event:
       type: object
       properties:
@@ -1194,6 +1221,7 @@ components:
         propertyName: event
     Domain:
       type: object
+      description: The bot's domain.
       properties:
         config:
           type: object
@@ -1206,7 +1234,7 @@ components:
           type: array
           description: All intent names and properties
           items:
-            type: object
+            $ref: '#/components/schemas/IntentDescription'
         entities:
           type: array
           description: All entity names
@@ -1215,9 +1243,13 @@ components:
         slots:
           description: Slot names and configuration
           type: object
+          additionalProperties:
+            $ref: '#/components/schemas/SlotDescription'
         templates:
           description: Bot response templates
           type: object
+          additionalProperties:
+            $ref: '#/components/schemas/TemplateDescription'
         actions:
           description: Available action names
           type: array
@@ -1261,7 +1293,7 @@ components:
                 description: Attachement payload
     Tracker:
       type: object
-      description: A conversations state
+      description: Conversation tracker which stores the conversation state.
       properties:
         sender_id:
           type: string
@@ -1270,7 +1302,7 @@ components:
           type: array
           description: Slot values
           items:
-            type: object
+            $ref: '#/components/schemas/Slot'
         latest_message:
           $ref: '#/components/schemas/ParseData'
         latest_event_time:
@@ -1290,6 +1322,16 @@ components:
         latest_input_channel:
           type: string
           description: Communication channel
+        latest_action_name:
+          type: string
+          description: Name of last bot action
+        active_form:
+          type: object
+          description: Name of the active form
+          properties:
+            name:
+              type: string
+              description: Name of the acive form
 
     Error:
       type: object
@@ -1363,7 +1405,7 @@ components:
             Accuracy of the classification,
             http://scikit-learn.org/stable/modules/generated/sklearn.metrics.accuracy_score.html
         is_end_to_end_evaluation:
-          type: bool
+          type: boolean
           description: True if evaluation is end-to-end, false otherwise
         precision:
           type: number
@@ -1390,3 +1432,44 @@ components:
           description: >-
             Sklearn classifcation report, see
             http://scikit-learn.org/stable/modules/generated/sklearn.metrics.classification_report.html
+    Slot:
+      type: object
+      additionalProperties:
+        $ref: '#/components/schemas/SlotValue'
+      example:
+        slot_name: slot_value
+    SlotValue:
+      oneOf:
+        - type: string
+        - type: array
+          items:
+            - type: string
+    SlotDescription:
+      type: object
+      properties:
+        auto_fill:
+          type: boolean
+        initial_value:
+          type: string
+          nullable: true
+        type:
+          type: string
+        values:
+          type: array
+          items:
+            type: string
+      required: ['type', 'auto_fill']
+    TemplateDescription:
+      type: object
+      properties:
+        text:
+          type: string
+          description: Template text
+      required: ['text']
+    IntentDescription:
+      type: object
+      additionalProperties:
+        type: object
+        properties:
+          use_entities:
+            type: boolean

docs/docker.rst

@@ -1,3 +1,5 @@
+:desc: Using Rasa Core with Docker.
+
 .. _docker:
 
 Using Docker

docs/index.rst

@@ -64,7 +64,7 @@ The Rasa Core dialogue engine
 
    architecture
    connectors
-   customactions
+   run-code-in-custom-actions
    slots
    slotfilling
    responses