Story #13390

Document API in API discovery document

Added by Tom Morris 8 months ago. Updated 8 months ago.

Status:
New
Priority:
Normal
Assigned To:
-
Category:
-
Target version:
Start date:
Due date:
% Done:

0%

Estimated time:
Story points:
-

Description

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).

History

#1 Updated by Peter Amstutz 8 months ago

  • Description updated (diff)

Also available in: Atom PDF