Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix API docs #10268

Merged
merged 10 commits into from
Nov 19, 2021
Merged

Fix API docs #10268

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8cbca90
Fix http-api docs
Nov 17, 2021
601dd11
Clarify model path in docs
Nov 17, 2021
ca8d70d
Merge branch 'main' into tayfun/10148-fix-api-docs
Nov 17, 2021
78596b9
Update docs/static/spec/rasa.yml
Nov 17, 2021
779e1b7
Fix swagger validation
Nov 17, 2021
0ae21d3
Merge branch 'main' into tayfun/10148-fix-api-docs
Nov 17, 2021
738b33f
Merge branch 'main' into tayfun/10148-fix-api-docs
Nov 18, 2021
8f70cfd
Update example in docs
Nov 18, 2021
ae0be53
Merge branch 'main' into tayfun/10148-fix-api-docs
Nov 18, 2021
ca55aad
Merge branch 'main' into tayfun/10148-fix-api-docs
indam23 Nov 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 79 additions & 15 deletions docs/static/spec/rasa.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,12 +482,55 @@ paths:
description: >-
The training data should be in YAML format.
content:
application/json:
schema:
$ref: '#/components/schemas/JSONTrainingRequest'
application/x-yaml:
application/yaml:
schema:
type: string
$ref: '#/components/schemas/YAMLTrainingRequest'
example: |
intents:
- greet
- goodbye

responses:
utter_greet:
- text: "Hey! How are you?"

utter_goodbye:
- text: "Bye"

session_config:
session_expiration_time: 60
carry_over_slots_to_new_session: true

pipeline:

policies:

nlu:
- intent: greet
examples: |
- hey
- hello

- intent: goodbye
examples: |
- bye
- goodbye

rules:

- rule: Say goodbye anytime the user says goodbye
steps:
- intent: goodbye
- action: utter_goodbye

stories:

- story: happy path
steps:
- intent: greet
- action: utter_greet
- intent: goodbye
- action: utter_goodbye

responses:
200:
Expand Down Expand Up @@ -718,7 +761,8 @@ paths:
summary: Replace the currently loaded model
description: >-
Updates the currently loaded model.
First, tries to load the model from the local storage system.
First, tries to load the model from the local (note: local to Rasa server)
storage system.
Secondly, tries to load the model from the provided model server configuration.
Last, tries to load the model from the provided remote storage.
requestBody:
Expand Down Expand Up @@ -1052,7 +1096,7 @@ components:
model_file:
type: string
description: Path to model file
example: "/models/20190512.tar.gz"
example: "/absolute-path-to-models-directory/models/20190512.tar.gz"
model_server:
$ref: '#/components/schemas/EndpointConfig'
remote_storage:
Expand Down Expand Up @@ -1407,19 +1451,40 @@ components:
type: integer
description: Time to wait between pulls from model server

JSONTrainingRequest:
YAMLTrainingRequest:
type: object
properties:
domain:
$ref: '#/components/schemas/DomainFile'
config:
$ref: '#/components/schemas/ConfigFile'
intents:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section should include all properties (missing ones from the domain include actions, entities, e2e_actions, config) and be ordered (IMO) by config.yml, then domain.yml, then the data files

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section should include all properties (missing ones from the domain include actions, entities, e2e_actions, config) and be ordered (IMO) by config.yml, then domain.yml, then the data files

@melindaloubser1 are you sure actions etc. would be handled here? I don't see it in stale docs either: https://rasa.com/docs/rasa/pages/http-api#operation/trainModel I've taken the example and schema from unit tests.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't all of this covered by #/components/schemas/DomainFile?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joejuzl It's not under domain anymore, request body is flattened. This is why I've newly added this schema. Also, examples inside schemas do not work for any content type except for JSON in redocly, so example keys were removed and a separate example on the same level as schema was added. The other thing is I've simplified the example, previously there were 6 intents in the example request, I've added 2 to show how a list can be sent, I think people can extrapolate that and add more intents if needed.

type: array
description: All intent names and properties
items:
$ref: '#/components/schemas/IntentDescription'
responses:
description: Bot response templates
type: object
additionalProperties:
$ref: '#/components/schemas/TemplateDescription'
session_config:
description: Session configuration options
type: object
properties:
session_expiration_time:
type: integer
carry_over_slots_to_new_session:
type: boolean
pipeline:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the change from #/components/schemas/ConfigFile?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joejuzl Similar to domain, request body is flattened, config key doesn't exist anymore.

Copy link
Contributor

@joejuzl joejuzl Nov 18, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there no way to include the contents of #/components/schemas/ConfigFile at the top level, i.e. without it being under its own key?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've tried using allOf but couldn't get it to work. To test this, I've run make livedocs in top level and then added:

    TrainingSchema:
      allOf:
        - $ref: '#/components/schemas/DomainFile'
        - $ref: '#/components/schemas/ConfigFile'

to the bottom of the file and referenced it in requestBody as:

          application/yaml:
            schema:
              - $ref: '#/components/schemas/TrainingSchema'

I don't see schema and only see any in the docs output in that case. @joejuzl @melindaloubser1 do you know a better way?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well that second part's schema should not be a list:

         application/yaml:
            schema:
              $ref: '#/components/schemas/TrainingSchema'

Notice the dash is missing. This is still not showing the schema, but instead of any, I get string (TrainingSchema)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately I haven't found another way either - Only experimented briefly but ran into the same issues you did @tayfun

description: Pipeline list
type: array
policies:
description: Policies list
nlu:
$ref: '#/components/schemas/NLUTrainingData'
responses:
$ref: '#/components/schemas/RetrievalIntentsTrainingData'
rules:
description: Rule list
type: array
stories:
$ref: '#/components/schemas/StoriesTrainingData'

force:
type: boolean
description: >-
Expand All @@ -1432,7 +1497,6 @@ components:
If `true` (default) the trained model will be saved in the default model
directory, if `false` it will be saved in a temporary directory
deprecated: True
required: ["config"]

NLUTrainingData:
type: string
Expand Down
28 changes: 0 additions & 28 deletions rasa/server.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1422,34 +1422,6 @@ def _test_data_file_from_payload(request: Request, temporary_directory: Path) ->
)


def _validate_json_training_payload(rjs: Dict) -> None:
if "config" not in rjs:
raise ErrorResponse(
HTTPStatus.BAD_REQUEST,
"BadRequest",
"The training request is missing the required key `config`.",
{"parameter": "config", "in": "body"},
)

if "nlu" not in rjs and "stories" not in rjs:
raise ErrorResponse(
HTTPStatus.BAD_REQUEST,
"BadRequest",
"To train a Rasa model you need to specify at least one type of "
"training data. Add `nlu` and/or `stories` to the request.",
{"parameters": ["nlu", "stories"], "in": "body"},
)
indam23 marked this conversation as resolved.
Show resolved Hide resolved

if "stories" in rjs and "domain" not in rjs:
raise ErrorResponse(
HTTPStatus.BAD_REQUEST,
"BadRequest",
"To train a Rasa model with story training data, you also need to "
"specify the `domain`.",
{"parameter": "domain", "in": "body"},
)


def _training_payload_from_yaml(
request: Request, temp_dir: Path, file_name: Text = "data.yml"
) -> Dict[Text, Any]:
Expand Down