Clarify recovery/verification API documentation

[Benehiko]

Preflight checklist

• I could not find a solution in the existing issues, docs, nor discussions.
• I agree to follow this project's Code of Conduct.
• I have read and am following this repository's Contribution Guidelines.
• This issue affects my Ory Network project.
• I have joined the Ory Community Slack.
• I am signed up to the Ory Security Patch Newsletter.

Describe your problem

The recovery API documentation shows all of the fields for the body on POST for all states.

https://www.ory.sh/docs/reference/api#tag/frontend/operation/updateRecoveryFlow

The verification API documentation doesn't even show the code method.

https://www.ory.sh/docs/reference/api#tag/frontend/operation/updateVerificationFlow

This might confuse some users since we don't indicate that the Recovery & Verification flows can have two states.

The recovery flow is submitted twice, once to get the email sent out to the email, and the second to submit the code sent out from the email.

The flow kind of looks a bit like this:

1. Create recovery flow
2. Submit email
3. Re-render form based on response (or get flow data through ID)
4. Submit code
5. Get redirected to settings flow on success OR handle form error

Describe your ideal solution

We should update the description to indicate what is required when.

Not sure how we could show multiple states with the OpenAPI spec.

Workarounds or alternatives

None

Version

latest

Additional Context

https://github.com/orgs/ory/discussions/54#discussioncomment-5314981

[Big-Brother-Man]

Hey @Benehiko thank you for opening this. It will definitely help users who struggled with the two path ways i.e. email, then code like myself. It took me a while to understand this separation as nothing pointed to this in the docs.

For the verification code not showing that is also something I struggled with and documented part of an issue.

Many thanks for your help!