the-grid / apidocs

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

Potential issue with JSON schema output #25

Open paulyoung opened 9 years ago

paulyoung commented 9 years ago

I see some JSON schema information displayed like this:

screen shot 2015-08-11 at 3 17 37 pm

In particular, I'm not sure if the "$ref": "base.json#/definitions/uuid" part is supposed to be displayed that way or if something has gone wrong with page rendering.

If it is correct, could someone point me to where base.json lives?

jonnor commented 9 years ago

@paulyoung base.json should be built from base.yaml (like all the .json files) https://github.com/the-grid/apidocs/blob/master/schemata/base.yaml

What do you think is wrong here?

paulyoung commented 9 years ago

It's not intuitive for me as someone reading the documentation what "$ref": "base.json#/definitions/uuid" means or where base.json can be found for me to view.

I thought maybe the intention was for the UUID section of base.json to be rendered inline here and perhaps something had gone wrong with that.

hannesstruss commented 9 years ago

It definitely would be helpful if the ref was clickable.