generating documentation

[Eric Stob]

Hi guys,

I got my validation to work!  this project rocks, thanks to all contributors!  I didn't use "extends", "id", and "ref" because I didn't have time to figure them out - but it works great even without that.

Now, I am looking for a tool that can generate documentation HTML given a JSON Schema file.

My first thought was Doxygen but I am not seeing any support for JSON schema in Doxygen.

Do you guys know a documentation system that can generate HTML docs from JSON Schema?  Or maybe an extension for Doxygen?

Thanks!

Eric

[nic...@gmail.com]

On Monday, 14 May 2012 22:58:19 UTC+2, Eric Stob wrote:

I got my validation to work!  this project rocks, thanks to all contributors!  

Awesome works like a charm hey? Don't stop there, what is a bit of validation without an automagicaly generated form based on your brand spanking new json-schema to see the validation in action.

Onde http://exavolt.github.com/onde/

jsonwidget http://jsonwidget.org/wiki/Jsonwidget-javascript

reformed http://bigbluehat.github.com/reformed/

We also have the json schema generator http://www.jsonschema.net/ and a few side by side on-line testing tools http://jsonschemalint.com/ & http://json-schema-tester.herokuapp.com/

   

I didn't use "extends", "id", and "ref" because I didn't have time to figure them out - but it works great even without that.

But yes that's about where the fun and games stop, I am also yet to find a solution for link extraction between the schema and the data entity, relative or absolute just to have it in a format that the browser would understand. There are countless other solutions for this specific problem but I already have a wheel I like, json-schema. Lets get back to this... 

 

Now, I am looking for a tool that can generate documentation HTML given a JSON Schema file.

My first thought was Doxygen but I am not seeing any support for JSON schema in Doxygen.

Do you guys know a documentation system that can generate HTML docs from JSON Schema?  Or maybe an extension for Doxygen?

I have also looked high and low and have to conclude that there are no json-schema documentation implementations anywhere to be found. So it is safe to say that we can start a new project without duplicating any existing effort. I am hoping to take it a few steps further if I may... quite a bit further. 

These are the cream of the crop in API documentation pickings IMO.

Mashery iodocs http://developer.mashery.com/iodocs

Awesome stuff but they are using their own schema as the layer to standardize the APIs, I have to disagree we already have a standard... well almost. 

https://github.com/mashery/iodocs/blob/master/public/data/linkedin.json

Swagger http://petstore.swagger.wordnik.com/#!/_user/getUserByName_GET

Very well done and inspiration to many including this ported version:

NelmioApiDoc https://github.com/nelmio/NelmioApiDocBundle#web-interface

But as you guessed it no json-schema and arguably not very RESTful either.

Apigee pulled out all the stops with great haste and might just have gone a bit overboard, ymmv.

Apigee - https://apigee.com/resources/linkedin

All things said and done, you'll have to agree, this is just brilliant =) got to have some of that attached to my endpoints, what do you think?

http://okfnlabs.org/recline/app/?url=demo#explorer 

This is what I think:

What about a complete discovery and RESTful api maintenance front-end based on json-schema? 

Implementation should be layered and modular, if you only want to use the documentation solution it should be possible, reuse and improve on the components already out there. Combine all the disbursed projects under one umbrella as a code agnostic and collaborative development powerhouse to the likes of ASF and Big Blue. Where we may share our knowledge and experiences while realizing best of breed pure RESTful solutions to not only simplify entry into this jungle of RESTful API development but to finally have some reference implementations as examples to facilitate real world use case comparison. Imagine being able to actual test a recommended specification before publishing which will decrease the huge gap between live hands on implementation products and the magnitude of book theory we've accumulated over the last 4 decades. Hopefully this simplifies the enormous task our RESTafarian mentors face everyday with continuous stuck up in the clouds speculative analysis of thumb-suck-proposals which can't be tested before they are let loose in the wild. Maybe they may also enjoy a well deserved break and join us in the trenches where all the fun happens and their advice gravely needed. Who knows maybe doc.Fielding might just live to see his vision of the true Internet-scale distributed hypermedia system realized, he might even have a chance to lend a hand, if we start working together and stop breaking everything.

What do you think? How much more "me too" mentality, false profits preaching misconceived gospels and running us off in tangents is it still going to take? We need advocates for the truth willing to keep a beacon of light on the path to truth for the lost and weary in their time of need. How many more abandoned one man projects will it take, how much more time wasted because valuable specifications expire incomplete [ just saying =) ] or how many more duplicated effort and incomplete solutions will you still start up, evaluate, test, compare, hack to compliance before you realize that you are doing it alone. We need a much higher standard of quality, there should be no excuse. I obviously skipped a generation or two or there is a serious lack in my upbringing but I just can't imagine that this is how it was in the past and what brought us to where we are today. It is time to take hands and head for a common goal which we can only accomplish if we realize we can do it together.

Right enough ranting lets map a plan of action:

1. This should go viral so those in the know can help, spread the call to arms every interested individual is welcome.

2. A fitting name is required which we can identify with and others can easily identify what we are doing.

3. Create a communal space at github, maybe where we can have the freedom to create separate repositories and fork other repositories all grouped under our namespace. Unless there is anything better we can us, suggestions?

4. Agree on a combined focus summarized as a mission statement and document a few simple conventions and practices from the start which will simplify integration and strengthen community. What about +1 voting who wants to agree?

5. Get to work, enough time has been wasted. 

    i) Re-submit the json-schema spec and ensure it gets approved. How can we accomplish this? To aid with momentum here are some suggestions:

        a. Find the latest and most up to date incarnation of draft-v4 and dust the cobwebs so that xml2rfc can stop complaining.

        b. Make it available publicly in HTML format for everyone to see.

        c. Identify what is outstanding and log these in a ticketing system.

        d. Identify volunteers eager to manage, support and facilitate the process officially.

        e. Roadmap a timed strategy to get it bubble wrapped and published.  

        f. Allow for input and suggestions during a window period while we also wrap up the other tasks at hand..

        g. Combine json-schema, json-reference, json-hypermedia, json-link into one specification.

        h. Agree on mime-type(s) and document the initial entities for inclusion in the spec and submission to IANA

        i.  Review, polish and finalize the draft so that we can all agree that we can publish it as a community together

      ii) Solve the hypermedia debacle by developing a follow your nose capable solution able to extract links represented by the schema mapped to living entities. 

      iii) Solve the generation of documentation from a completed schema

      iv) By now several initial project would have started in parallel to develop reference implementations in different languages while aiding the specification project rectifying any hiccups and walk the spec through its paces before we all agree that it is ready to be published.

Is this a workable strategy? Please share your insights and wisdoms as I have never done anything at this scale before, neither should this act be seen as craving attention, glory or deserving special treatment. If the is someone that takes offense may I humbly apologize this is not my intent. If you agree with me, I think what has been mapped out is a viable action plan for starters which will work, if we make it work together. Please don't misinterpret, these are only suggestions and we wouldn't be doing it together if you couldn't say that you disagree, lets hear what everyone has to say.

Do something amazing today. 

[Eric Stob]

I don't know about all that, but it seems that there exists demand for a documentation tool supporting json schema.

I found a few things that seem helpful to achieving this.

http://ajaxstack.com/jsonreport/

http://beebole.com/pure

--
You received this message because you are subscribed to the Google Groups "JSON Schema" group.

To view this discussion on the web visit https://groups.google.com/d/msg/json-schema/-/NfmkIlnX9WYJ.

To post to this group, send email to json-...@googlegroups.com.
To unsubscribe from this group, send email to json-schema...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/json-schema?hl=en.

[Walter]

One of the key issues connected with documentation generation from
JSON Schema is internationalization.

Specifically, if you are planning to generate documentation based upon
fields such as 'title' and 'description', then be aware that this will
mean that you cannot easily generate multilingual documentation.

To resolve this, maintain 'title' and 'description' in
language-specific schema files that use 'extends' to provide
language-specific information to the central, shared language-neutral,
structure-only schema.

- Walter

[Eric Stob]

You can put anything you want in description.
Like escaped json.

Sent from my iPhone

> --
> You received this message because you are subscribed to the Google Groups "JSON Schema" group.

[Walter]

> You can put anything you want in description.
> Like escaped json.

True. However, uuencoded gzip-compressed escaped JSON is not going to
port very well, and is not very human readable/editable.

Practically, for my own applications it makes sense to 'extend' on a
per-language basis in order to maintain clarity within schema
documents.

Each to their own.

- Walter

[Richie Vos]

We also are actively looking to do json schema based documentation and api discovery. Great list of links. One really nice one we've found is the google discovery api:

Docs: https://developers.google.com/discovery/

Format definition: https://developers.google.com/discovery/v1/reference

Example top-level, api of apis (api of services) endpoint: https://www.googleapis.com/discovery/v1/apis

Example specific api (service) endpoint: https://www.googleapis.com/discovery/v1/apis/adsense/v1/rest

The reason I liked that one is it has a fairly well defined format. It is json based, and uses json-schema for the response definitions. It does responses and requests. And most of their examples are RESTful. I'm quite curious if anyone else has opinions on that api.

We're likely going to test out basing our solution on that, plus adding support for return codes ala swagger.

The internationalization concept is also interesting, and a very good point. The google discovery style api doesn't appear to have any internationalization support built-in. I personally do not consider that a blocker for my uses cases.

- Walter

[Eric Stob]

Thank you for this information.

I investigated this but I don't see a way to generate documentation with it

Also they have lots of example of how to consume service with it, but no example of how to create / define service with it.

Also this seems very geared towards restful http api's - which is a small subset of the uses of JSON, it seems kind of irrelevant for other use cases.

Also - I did not find any source code, it seems this is not open source and so it can not be modified to fit my use case.

[Matthew O'Donoghue]

I've been working on something for documentation for a little while now but it's finally reached a stage where I feel that people can actually use it so please take a look at :  https://github.com/mattyod/matic and feedback is more than welcome.

There is an example project which you can download and build too at:  https://github.com/mattyod/matic-simple-example You will need jade installed to run this.

I'm quite interested in exploring the links object within a schema and determining if this can be used sensibly in conjunction with documentation so would also appreciate people's thoughts around that.

Matt

[lauren...@gmail.com]

As mentioned in other posts, there is an on-the-fly in-browser document generation tool for json-schema I worked on recently: https://github.com/lbovet/docson

[Andrew Biggs]

On Monday, May 21, 2012 at 4:53:29 PM UTC-6, nic...@gmail.com wrote:

On Monday, 14 May 2012 22:58:19 UTC+2, Eric Stob wrote:

Do you guys know a documentation system that can generate HTML docs from JSON Schema?  Or maybe an extension for Doxygen?

I have also looked high and low and have to conclude that there are no json-schema documentation implementations anywhere to be found. 

Was looking around for a JSON-Schema to HTML documentation generator today, and came across this old thread.  Anyone know if such a beast has come into existence since then?

Cheers,

Andrew

[Andrew Biggs]

Ha, just noticed the reply on the same thread mentioning https://github.com/lbovet/docson, will give that a try.

Cheers,

Andrew

 

[Jason Desrosiers]

You might want to checkout jsonary as well (htttp://jsonary.com).  It supports JSON Hyper-Schema rather than just JSON Schema like docson (as far as I've seen).  This means that a jsonary json browser can not only describe your JSON documents, it also provides links and forms describing what you can do with that document.

The following link is a jsonary JSON API browser that I use to browse hyper-schema described APIs.  As long as your API has CORS support, you just need to put the endpoint into the json-browser and you can browse any API that is described by JSON Hyper-Schema.

http://json-browser.s3-website-us-west-1.amazonaws.com/?url=example.json