undefined | Better HN

0 pointsconorgil14511y ago0 comments

I could not agree more strongly that working on code, docs, and tests as a single unit is an excellent approach to development. I think the best way to convince most developers of doing this is to create tools which make it as automated as possible. If using a tool actually makes their lives easier to accomplish something they already do (write tests? write docs?) and they get the other for free, then that is a huge selling point.

I had a similar idea about using JSON Schema to validate my API. However, a few issues that I thought of and a few I discovered while researching:

1) I am not aware of a decent JSON Schema editor. It has been on my wishlist/TODO list for a looong time to write one myself which has similar capability to something like Oxygen for XML [1], but I have not had the time. Do you plan to write and update the JSON Schema by hand?

2) I have not researched them in great detail yet, but Swagger [2] and API Doc [3] seem to have already defined something similar to what I had in mind with JSON Schema. Have you looked into those tools yet?

[1] http://www.oxygenxml.com/index.html [2] https://helloreverb.com/developers/swagger [3] http://apidoc.me/doc/gettingStarted

0 comments

1 comments · 1 top-level

gjtorikian11y ago

> Do you plan to write and update the JSON Schema by hand?

Currently, yes, unfortunately. ;____; We've talked about doing it in an intermediate format, like YAML, which is slightly less painful, but....ugh. Years ago I wrote a very badly-coded-but-essentially-functional tool called Panino, which converted Markdown-to-JSON: https://github.com/gjtorikian/panino-docs/tree/master/lib/pa....

I see that some people have picked up on that and ran along with it, too: https://github.com/apiaryio/mson. So there might be something there to explore.

2. I've never looked into either. I know Swagger is used by several companies, like Twitter, but API Doc is new to me.

j / k navigate · click thread line to collapse