Orchestrating OpenAPI Services improvements

[LuboTerifaj]

During #591, there were identified several issues that might need to be updated.

Chapter: https://sonataflow.org/serverlessworkflow/main/service-orchestration/orchestration-of-openapi-based-services.html

Issues

• There is a prerequisite "You have installed the tooling."

  • It should be specified which part of tooling is necessary to be installed in this chapter.

• There is a mixed content in OpenAPI function definition. The content could be better separated.

  • OpenAPI function definition in workflows
  • Locating and accessing OpenAPI specification files

• Missing introduction of OpenAPI "request path" and "request body"

  • In procedure, there is : "In the following example, the parameters are part of the request body:"
    • It is not clear, what is meant by "request body" here. The workflow example follows that seems unrelated from user perspective.
  • In procedure, there is : "For more information about mapping parameters in the request path instead of request body, you can refer to the following PetStore API example:"
    • Same here, it is not clear what is meant by "request path" and "request body".

• There is a mixed content in Accessing functions in the workflow states

  • Accessing the functions in workflow states
  • Using OpenAPI specification
    • In addition, there is missing description in this section, how the "Example Petstore OpenAPI specification excerpt" is used.

• Missing description, what "sanitizied" means in "To configure the endpoints, you must use the sanitized OpenAPI specification file name" in Configuring the endpoint URL of OpenAPI services

• In Procedure, there is "The configuration key must be set as a valid environment variable."

  • There is missing description how to set it.

• In Procedure, there is "For example, a file named as subtraction.yaml contains the configuration key as subtraction_yaml."

  • The file in examples doesn't contain any key. The description should be changed to something like "file named as subtraction.yaml is mapped to the configuration key as subtraction_yaml."
  • Please ensure, enough information is provided how and where the configuration key is used, if not already provided.

• In Procedure, there is "You can use the same configuration key on each property that is related to the Quarkus REST client as shown in the following URL configuration example:"

  • Missing description where the URL should be configured.
  • Although the description can be found in the next step, it is not a good approach and it should be rewritten.

Acceptance criteria

All issues above are resolved.