Fix API docs

[tayfun]

Proposed changes:

Fixes #10148

• Updates /model/train endpoint in docs to only accept YAML input
• Updates /model endpoint to clarify model path

[indam23]

Mostly concerned about the function removal - not sure that should be happening here?

[indam23]

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

[tayfun]

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.

[joejuzl]

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

[tayfun]

@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.

[indam23]

Same on this section: reorder by config.yml then domain.yml then data, and add all keys even if they're empty e.g. actions: []

[tayfun]

Same on this section: reorder by config.yml then domain.yml then data, and add all keys even if they're empty e.g. actions: []

@melindaloubser1 I don't think actions are used here. I don't understand the ordering, why would it session_config come before others? Or do you mean pipeline comes first, then policies?

[indam23]

For this particular example, there are no custom actions to pass, so you are correct. However, in a bot with custom actions, or slots, or entities, these sections would need to be included.

Re. the ordering: Sorry for the shorthand, I meant the contents of config.yml, so yes, pipeline + policies, then domain content (intents, entities, actions, e2e_actions, forms, slots, responses, config<- this is a key in the domain in 3.0, which is quite confusing) then content of nlu, rules and stories. It's not required to do it this way for the example to work, but will make it much easier for readers to understand the example

[tayfun]

@melindaloubser1 Yeah I meant do you know custom actions are used if provided in request body like here? I don't see that in code, and I don't see them being tested in unit tests. I wouldn't be surprised if not all CLI options were supported here.

[indam23]

They would have to be supported to train on stories which include custom actions I believe

[joejuzl]

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

[joejuzl]

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

[tayfun]

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

[joejuzl]

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?

[tayfun]

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?

[tayfun]

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)

[indam23]

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

[joejuzl]

Bit annoying we can't inline the other schemas... but at least it's correct now! 😁