search

the-grid / apidocs

API documentation for The Grid
https://developer.thegrid.io
44 stars 9 forks source link

Schema definitions should be linked or inlined in HTML docsform #27

Open jonnor opened 9 years ago

jonnor commented 9 years ago

Right now we just raw-dump the schemas into the blueprint. This is useful-ish, but things like $ref: someother-schema is confusing.

References should be resolved, and then put links into the HTML to navigate up/down between these. For single base definitions (which are usually very short) it might be nicer to inline. Also, there should probably be a link to the schema itself (in .yml and .json format), so people see where it comes from.

Came up in #26

automata commented 8 years ago

Using something like docson to generate an HTML with all schemas in one page could be useful to navigate too.