Syndesis: Document warnings

[pwright]

This is a...

[ ] Feature request
[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[x ] Documentation issue or request

Description

Add docs for warnings, eg:

• Unable to determine the scheme to use: OpenAPI specification does not provide a `schemes' definition and the specification was uploaded so the originating URL is lost.
• Operation PUT /api/fruits/{id} does not provide a response schema for code 201
• Operation DELETE /api/fruits/{id} does not provide a response schema for code 204

user is unsure what to do

[KurtStam]

@pwright Hi Paul, I'm note sure which use case this is? Oh I think it is https://github.com/integr8ly/tutorial-web-app-walkthroughs/tree/master/walkthroughs

So you can edit the schema in apicurito using the 'edit' button to add a schema definition, is that what you want o have added in the docs? Is that what you are looking for, or do you want an updated schema in the GitHub repo?

[zregvart]

We can certainly reword those messages to make them a bit clearer. @pwright what bits you found unclear that need more explaining?

Other than that we should not be warning about missing response schema for 204, that HTTP status denotes that there will be no response.

[pwright]

@KurtStam I'll just explain with one example, user sees the warning:

Operation PUT /api/fruits/{id} does not provide a response schema for code 201

It's a warning, so maybe user needs to create a response schema for code 201, but my eng team say it's not necessary and my readers say they want to know why there's a warning.
My question is 'should there be docs for these warnings?' or are they supposed to so intuitive that they don't need docs?

[pwright]

@zregvart The fact that there were 3 warnings for something that Eng says is 'good' was surprising. Perhaps 'Info' rather than 'Warning' would help here?

Lemme read this one as a novice:
"Unable to determine the scheme to use: OpenAPI specification does not provide a `schemes' definition and the specification was uploaded so the originating URL is lost."

Seems like Fuse is unable to determine something, why didn't it fail? something was lost, and yet the process didn't fail. This is a warning, so I should prob do something, but what?

[zregvart]

Let me explain this a bit so we can find a way to make it a bit clearer.

The first warning:

Unable to determine the scheme to use: OpenAPI specification does not provide a `schemes' definition and the specification was uploaded so the originating URL is lost.

The protocol scheme that the connector needs to use can be either http or https, this information can be provided in the OpenAPI document, if it's not provided then it is (as defined by the specification) the protocol scheme from the URL of the OpenAPI document, this is lost if the document is uploaded vs pointed to by URL.

Without the scheme we can't create the full endpoint URL of the API as the OpenAPI document then contains only the hostname (no scheme).

Two last warnings are manifestation of this fact: a connector action will be created and the type information on those actions will be missing.

This is what we currently have in the downstream Red Hat product documentation:

The more detail that the OpenAPI document provides, the more support Fuse Online can offer when connecting to the API. For example, the API definition is not required to declare data types for requests and responses. Without type declarations, Fuse Online defines the corresponding connection action as typeless. However, in an integration, you cannot add a data mapping step immediately before or immediately after an API connection that performs a typeless action.

What I would propose

1. we need to remove the warning for missing response schema for code 204
2. let's reword the does not provide a response schema for code into ... operation does not provide a response type, specify it to have type information available and the response of the API invocation available in the integration flow, ignore this if the operation doesn't provide a response or the type information is not needed
3. we could rethink the way the API endpoint is defined, some thoughts:
   
   
   
   • as we specify the Host with the full URL anyhow (like https://api.example) we can remove the protocol scheme warning as it can be deduced from the Host
   
   
   • we can remove the Host and Base path from the custom API connector wizard, users get to specify those anyhow when creating a connection
   
   
   • (come to think of it) we don't need the Base path at all, it's specified in the OpenAPI document and user can change it there if needed
   
   

Would this be bit better @pwright?

Also @TovaCohen might have some thoughts on this.

[pwright]

What i don't understand is "why didn't this fail?" Did fuse assume http as the scheme and proceed? (if so, that should be the message)
As an integreatly user, I don't really care too much about the openapi spec (sorry), the quote from the doc looks useful, something like:

Warning: No type declaration. You cannot add a mapping step.

[TovaCohen]

If the error message gets reworded, I would use complete sentences, something like:

The OpenAPI document does not define a response type for the xyz operation. You can ignore this if type information is not needed in the integration flow. If type information is needed in the flow, for example to map response data, define the response type in the OpenAPI document.

[stale[bot]]

This issue has been automatically marked as stale because it has not had any activity since 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions!

[pwright]

feel free to close if there's no action the group want's to take

[stale[bot]]

This issue has been automatically marked as stale because it has not had any activity since 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions!