Ruby API reference docs: inaccuracies and broken examples

[zarqman]

Hi. Wanted to provide some feedback on the xero-ruby API reference docs.

I suspect most of this is in your generator that produces docs from your OpenAPI spec.

First, the examples provided are mostly not valid against the SDK. For example, https://xeroapi.github.io/xero-ruby/accounting/index.html#api-Accounting-createBankTransactions ends with this:

begin
  response = xero_client.accounting_api.create_bank_transactions(xero_tenant_id,
    bankTransactions, summarize_errors, unitdp)
  return response
rescue XeroRuby::ApiError => e
  puts "Exception when calling create_bank_transactions: #{e}"
end

However, the key line needs to be:

response = xero_client.accounting_api.create_bank_transactions(xero_tenant_id,
  bank_transactions: bankTransactions, summarize_errors: summarize_errors,
  unitdp: unitdp)

Likewise on get* type requests. For example, at https://xeroapi.github.io/xero-ruby/accounting/index.html#api-Accounting-getContacts, this

response = xero_client.accounting_api.get_contacts(xero_tenant_id, if_modified_since, 
  where, order, ids, page, include_archived, summary_only)

should be this:

response = xero_client.accounting_api.get_contacts(xero_tenant_id, 
  if_modified_since: if_modified_since, where: where, order: order, ids: ids, 
  page: page, include_archived: include_archived, summary_only: summary_only)

The docs should note that all the various :keyword parameters are generally optional.

Second, some of the listed parameters are incorrect or confusingly identified. Again, using getContacts as an example: There is a section labeled 'Header parameters'. However, that these are sent using HTTP headers is abstracted entirely by xero-ruby (thankfully!) and this just confusing. For purposes of the SDK, they are simply query parameters The parameter descriptions are also incomplete. where says it takes a String. While true, it also takes certain arrays. And what the String (or Array) should contain is not identified on that page. Even a link back to the xero-ruby README, which is the only place I found such info, would be super helpful. For another example, IDs says it takes array[UUID]. That's not meaningful Ruby code and is unclear exactly what is required. Does the array contain Strings or a special UUID class? Adding an example in the parameter description would help greatly. Also, the docs list this param as IDs, but in ruby it's going to be :ids as noted above. Likewise, many of these are listed in snake-case, but aren't in ruby, ie: includeArchived should be shown as include_archived.

Third, it'd be super helpful if the SDK docs showed an example of an actual response, or at the least clarified how to access the embedded data, since it's nested behind weird nested methods, such as needing to look at response.contacts and not just at response.

Fourth, it be helpful if each API method included a link back to the non-SDK docs for more specifics about what the valid params values are, what response values are expected, etc. For example, getContacts would link back to https://developer.xero.com/documentation/api/accounting/contacts#get-contacts.

Fifth, it'd be helpful for the list of API methods on the left to be grouped by Resource first, not sorted purely alphabetically. That is, sort based on Account, Contact, and so on first, and then sub-sort on create*, delete*, get*, update*, etc.

All the above is merely representative. These inaccuracies and confusing parts exist throughout. Ideally much can be fixed inside your code/docs gen. However, even if it requires manual effort, I would encourage it to be undertaken. Good docs are really valuable and worth having!