Project

General

Profile

Actions

Idea #13390

open

Document API in API discovery document

Added by Tom Morris almost 6 years ago. Updated 28 days ago.

Status:
New
Priority:
Normal
Assigned To:
-
Category:
-
Target version:
Story points:
-
Release:
Release relationship:
Auto

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).
Actions #1

Updated by Peter Amstutz almost 6 years ago

  • Description updated (diff)
Actions #2

Updated by Peter Amstutz over 2 years ago

  • Target version deleted (To Be Groomed)
Actions #3

Updated by Peter Amstutz about 1 year ago

  • Release set to 60
Actions #4

Updated by Peter Amstutz 28 days ago

  • Target version set to Future
Actions

Also available in: Atom PDF