Request: Improve Formatting of POST Call Documentation

Canada Post’s POST calls support a wide variety of body element combinations. For example, the "Get Rates" call includes over 30 different elements, which you can view on our legacy portal.

Currently, the IBM portal tool pulls the schema for these body elements directly from the YAML and displays it as raw code in a block format. This results in a confusing and hard-to-read experience for developers – especially when trying to interpret the business rules associated with each element. The issue is made worse by the presence of both English and French definitions within the same YAML. (See Screenshot 1)

We’re requesting an enhancement to display the POST schema in a more user-friendly format – similar to how the IBM portal currently presents query parameters. (See Screenshot 2)

For reference, Square uses a more intuitive format for body elements, which significantly improves readability. You can view an example here, and the corresponding schema in their YAML file which is attached and viewable at line 59124. 

In this example from Square you can see how the body elements in the schema are floated out element by element and showed with it’s corresponding description and example that’s defined in the schema. This is type of layout is ideal for how complex our documentation can get. (See Screenshot 3)