[AN-242] Update MethodQuery schema in Swagger docs

[sam-schu]

Jira ticket: https://broadworkbench.atlassian.net/browse/AN-242

Context

The MethodQuery schema in Swagger is used only by a single endpoint: POST /api/methods. The description of this endpoint specifies that namespace, name, payload, and entityType must be included in the request body, which has been verified, but the MethodQuery schema does not list these properties as required. Also, the schema provides default values for all of its properties, none of which are actually used by Orchestration in the case that they are not provided.

Changes

• Updated the MethodQuery schema to make the namespace, name, payload, and entityType properties required and to change all default property values to example property values.

Testing

• Tested in a BEE that the Swagger page is updated.

Visual aids

Before:

After:

I, the developer opening this PR, do solemnly pinky swear that:

• I've followed the instructions if I've made any changes to the API, especially if they're breaking changes
• I've updated the FISMA documentation if I've made any security-related changes, including auth, encryption, or auditing

In all cases:

• Get two thumbsworth of review and PO signoff if necessary
• Verify all tests go green
• Squash and merge. Make sure your branch deletes; GitHub should do this for you.
• Test this change deployed correctly and works on dev environment after deployment

[LizBaldo]

Would it make sense to move what used to be the default into an example section in the description fields instead? It does look like useful information, but I agree that they are not defaults

[aednichols]

The defaults are pretty much already used like examples, I do find them useful in this context.

[sam-schu]

@aednichols I removed the defaults in line with the specification, which states that "[t]he default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided." Do we often enough use defaults contrary to this definition to represent examples that are not actually used as defaults by the backend that I should leave them as is?

[aednichols]

If there's a way to adopt the spec and preserve the example payloads, I'm on board with that.

[aednichols]

It looks like Leonardo does something reasonable with the example: key.

Swagger link
code link

[sam-schu]

@LizBaldo @aednichols Please take a look at the updated PR comment and let me know what you think. I added the example property values directly to the schema, and I confirmed that this does populate the "Example Value" for the request body in the endpoint that uses it.

[aednichols]

Nice 👍

Most likely, this Swagger was written before example existed. Good to get things up to date.