Create API documentation

[JeroenDeDauw]

The API is self-documents its endpoints to some extend. This is however not very detailed and other classes of information are needed by consumers.

• API endpoints
• Supported parameters, supported headers, post format and result formats
• Endpoint agnostic rules such as timestamp formatting
• Policy information such as rate limiting

GitHub API docs: https://developer.github.com/v3/

[addshore]

Could / should use swagger spec

https://github.com/swagger-api/swagger-spec http://swagger.io/specification/

[JeroenDeDauw]

Seems like there are two obvious options:

• Use https://github.com/zircote/swagger-php to generate the swagger spec from stuff in docblocks
• Create and maintain the swagger spec in JSON

The former has the advantage of putting the information close to the routes. The later has the advantage of not having to use some magical docblock syntax with no editor support whatsoever.

[JeroenDeDauw]

Apparently maintaining it in YAML (from which the JSON can be generated) is also an option: http://swagger.io/swagger-editor/

[JeroenDeDauw]

swagger-php has Silex integration via https://github.com/jdesrosiers/silex-swagger-provider

This might also be useful: https://github.com/kbrabrand/silex-swagger-ui

They both appear to be somewhat out of date though

[JeroenDeDauw]

As far as I can tell, going with the (non-generated) JSON is the simplest and perhaps also easiest approach. Using something like silex-swagger-ui would be good, since else the UI files need to be added to the repo. There is a fork of silex-swagger-ui that has the latest version of the Swagger UI, see https://github.com/kbrabrand/silex-swagger-ui/issues/6

[JeroenDeDauw]

The posts at https://github.com/jdesrosiers/silex-swagger-provider/issues/9 suggest Swagger might not be so good for our use case and that http://json-schema.org/ might be better. I've heard good things about json-schema.org for documenting REST APIs before.

[JeroenDeDauw]

https://github.com/JeroenDeDauw/QueryrWebsite