Arvados

Discovery document is generated by schema_controller by introspecting on the Rails controllers.

This has some weird side effects, such as redundant methods "index" (we prefer "list"), "show" (we prefer "get") and "destroy" (we prefer "delete").

Some of the things published in the discovery doc are obsolete or just completely wrong.

Current documentation in the discovery is a generic template description that is repeated for each type.

Object properties are derived from ActiveRecord columns. Where should descriptions go?

API calls that are not generic use "_#{action}_requires_parameters" to supply parameter details.

• Extend annotation embedded in Ruby, or store in a separate file and merge it in?
• If separate file, what format? Could we use OpenAPI?
• Task should include moving human-annotated content out of static documentation and autogenerate http://doc.arvados.org/api/
• Need to avoid "multiple sources of truth" problem. Discovery document generation should warn (error?) if there is a mismatch between external file and API server (missing/extra parameters, methods).