Skip to content

Change APIdoc to a less brittle approach for API documentation

We would like to implement APIdoc in a way that would be less/not reliant on an arbitrary order like the decorator tower currently is. As it stands, forgetting to @returns, or adding an extra @arg at the end of the decorator stack irremediably breaks the documentation endpoint AND the documented endpoint, as well as all other browsing routes that rely on it.

The new approach should manage to separate documentation data and execution data clearly, instead of carrying documentation data over no matter what.

As per @olasd 's comment on !28 (closed):

! In !28 (closed), @olasd wrote:

! In !28 (closed), @jbertran wrote: Note:

  • I'm not entirely satisfied (in general with apidoc) that my way is the right way. Don't hesitate to suggest big changes in the approach for the classes/modules.

Hey,

I started doing inline reviewing, and then I noticed the following comment

Caution: this MUST be the last decorator in the apidoc decorator stack,
or the decorated endpoint breaks

This really makes me wonder whether the "decorator tower" is the right approach for this problem. I think your currently proposed approach is workable and you should not take this as a blocker for merge, but rather as something that might be improved in the future.

The problem we're trying to solve is documenting, in a DRY and declarative way, API endpoints.

What that means in practice:

  • We have one view for the API endpoint
    • This view can be accessed by one or several routes parameterized with typed arguments
  • We declare the documentation for the API endpoint, its parameters, its return values, using a declarative system
  • We need to generate a "documentation route" allowing access to the documentation for the given API endpoint
  • We collect all the "documentation routes" inside an API index

The current tower of decorators approach is brittle, as it depends on the order of decoration to do its work in the right order.

We might be better off with a class/metaclass approach such as the one used for Django models, or Flask class based views.

That way, we can use the whole class declaration as our "structured documentation data", and run the whole code in one fell swoop without caring about the order of declarations.

Migrated from T558 (view on Phabricator)