Specifying action parameters in the inputs array or the annotations one

[brunogirin]

Issue

Action parameters specified in the inputs array are not visible through the WSK CLI while parameters specified in the annotations.parameters array are visible.

Expected behaviour

How the inputs and annotations.parameters arrays work should be documented and the tests should reflect this.

Details

I am trying to specify action parameters in the manifest so that those parameters are visible when you run wsk package get <package> --summary. Reading through the wskdeploy tests suggests that this should be done usign the inputs field so I created this manifest:

packages:
  hello:
    version: 0.0.1
    license: ISC
    actions:
      hello:
        function: hello.js
        runtime: 'nodejs:10'
        inputs:
          name:
            type: string
            description: name of a person
          place:
            type: string
            description: location of a person

However, when I deploy this and get the package summary, I get none defined (queried via the ibmcloud CLI):

$ bx wsk package get hello --summary
package /ConsiderateGroupDev_bruno/hello
   (parameters: none defined)
 action /ConsiderateGroupDev_bruno/hello/hello
   (parameters: none defined)

Looking through the cloudant package install script, it uses annotations and parameters instead so I created a different manifest:

packages:
  hello:
    version: 0.0.1
    license: ISC
    actions:
      hello:
        function: hello.js
        runtime: 'nodejs:10'
        annotations:
          description: Generate a simple greeting message
          parameters:
            - name: name
              required: false
              description: the name of a person
            - name: place
              required: false
              description: location of a person

When deployed, the parameters for the action are now documented:

$ bx wsk package get hello --summary
package /ConsiderateGroupDev_bruno/hello
   (parameters: none defined)
 action /ConsiderateGroupDev_bruno/hello/hello: Generate a simple greeting message
   (parameters: name, place)

I therefore assume that:

• the first form allows you to specify the value of inputs in a deployment manifest,
• the second form allows you to specify details of inputs as annotations for documentation purposes.

If this is correct, both forms should be included in the tests and documented. From the perspective of developers writing manifests, having two forms is confusing, especially when they overlap but don't quite do the same thing. It would be a lot easier if all parameter details, including type, value and description, where defined in the same block in the manifest, for the tool to work out how to deploy it.

For completeness, here is the code for hello.js:

function main(params) {
  const name = params.name || 'World';
  const place = params.place || 'Space';
  return {
    message: `Hello ${name} in ${place}!`
  }
}

[brunogirin]

Addendum: when I use the inputs structure and I create an API that calls the function, I get this error when calling the API with curl, suggesting that the inputs structure marks the parameters to reserved properties that the API gateway can't set:

{
  "code": "61b04fe092db97ce4f223069a4b0e0b3",
  "error": "Request defines parameters that are not allowed (e.g., reserved properties)."
}