User:APaskulin (WMF)/API doc tools

apiDoc
The apiDoc tool creates HTML documentation from code annotation. It supports JS, PHP, and several other languages. See the docs for an example of the HTML output.


 * The annotation format is more compact than swagger-php (15 lines added to a handler), resulting in less clutter in the source files. However, unlike a Swagger spec, example responses are not generated from response schemas, so examples need to be embedded in the source file. Since many MediaWiki-related API responses are long and complex, this would result in too much clutter in source files.
 * The simplest annotation style is shown below. However, there's also the ability to change the Success 200 and Error 4xx headings (ex: ).
 * There's a nice sample request feature, but it only accepts a sample URL, not the ability to customize path or query parameters. This makes the parameter interface for sample requests a bit confusing.
 * No obvious support for translation, but it may be possible through the extension interface.

Example source
LanguageLinksHandler.php

swagger-php
The zircote/swagger-php tool generates a Swagger spec from code annotations.


 * The tool requires adding a significant number of lines to code files. In this example: 100 lines added to the handler and 12 lines added to the entry point, compared with 84 lines in the resulting spec.
 * The tool supports context-aware annotations, but it seems that our handlers don't work the same way as the examples.
 * This example doesn't include error schemas, which I expect could be constructed using variables.
 * Need to look into using oneOf to document multiple responses per response code.
 * This example separates the annotations into two blocks: one with the path and responses and one with the response schema. To break up theses 50+ line blocks, it would be nice to place doc annotations as close as possible to the code they describe. However, the tool requires responses to be in the same annotation block as the path definition. Schema properties can be distributed, but it requires extra annotation syntax, adding complexity and further code file bloat. See this example.

Alternative annotation organization
Here's an example of an individual property described separately and pulled into the parent schema:

Compared with:

Swagger output
Paste into Swagger Editor to see rendered output.