On a recent project, my team agreed that we needed some way to validate and document the JSON coming in and out of our API. We had already settled on using JSON Schema as the means to describe the API, so determining how to validate (and document) JSON Schema was next on the to-do list. I did tons of research into how to best accomplish such noble tasks. OK, OK, “tons of research” really means “look for gems that do this already”. I also consulted my past experience with things like Grape and Swagger, but we aren't using Grape here and I couldn't find anything that would allow me to easily incorporate Swagger. Even if I did, that's only docs, without and validation.
The long and short of it (that's "old person talk" for TL;DR) is, if you want to document your API, validate requests and responses, and use JSON Schema, it's a bit of an effort. There are approaches, such as iodocs, but I didn't want to have to install Redis, use Node, etc. just to get docs. Also, there are plenty of tools out there to generate docs once you have the schema, but they don't give much help in creating the schema. I quickly learned that, no matter which tool or direction I chose, it was going to be a lot of manual effort to get this done. I am hoping this article gets anyone else with the same goal further up the path.
Continue reading %Document Your JSON API Schema with PRMD%
by Glenn Goodrich via SitePoint
No comments:
Post a Comment