List API parameters alphabetically, with required parameters on top
Proposal
Currently, an API endpoint's documentation may list something along the lines of this format:
POST /projects/user/:user_id
Attribute | Type | Required | Description |
---|---|---|---|
allow_merge_on_skipped_pipeline |
boolean | {dotted-circle} No | Set whether or not merge requests can be merged with skipped jobs. |
analytics_access_level |
string | {dotted-circle} No | One of disabled , private or enabled
|
.... | .. | ... | .... |
name |
string | {check-circle} Yes | The name of the new project. |
.... | .. | ... | .... |
In the above example, I believe for it to be better if the name
attribute was listed on top.
Aside from this proposal, I would also like to propose ensuring the listing of attributes to be alphabetically sorted by way of tests in our pipeline, to ensure that future commits won't change this order.
update: As per Mike's note:
This was discussed during the Write the Docs conference -- there's an expectation that API parameters are searched in the same order as the output to a REST call.
Readers can then compare their JSON formatted output directly to tables in our docs.
With that