New generator html documentation


#1

Hello, we are working on html documentation generator from raml specification. Project site http://raml2html.leanlabs.io/

We need your help, please evaluate the project.

Project documentation: http://raml2html.leanlabs.io/documentation


#2

How does it differentiate to the existing tools around HTML generation, just out of curiosity :wink:


#3

The main differences are:

  1. syntax highlight in examples
  2. json schema validation and references inclusion
  3. extended support for securedBy section - full description of security schema inluded in generated HTML for protected resources.

#4

Do you plan to contribute your changes to the existing or leaving it as a separated instance?


#5

My project is written from scratch, and I am planning to develop as a separate project.


#6

So basically you’re building a single page output for RAML documentation with support for JSON Schema? I hope my being honest doesn’t offend…but the “demo” look I don’t care for. I find it more difficult to read than the current RAML2HTML. However, I think you are attempting to do a similar 3-column layout like the Stripe API does… or possibly following the Slate (https://github.com/tripit/slate) style?

I’d also recommend another path for you to consider… using the raml-generator project instead of a fork of raml2html. I say that primarily because I am hoping (pushing for…??) the use of the raml-generator project as a sort of RAML “central” build tool that could be used to generate any sort of output from a RAML doc, including SDKs, test code, documentation, server side code, etc. By contributing any work back to this project, everyone could potentially benefit, and possibly have more than one choice with regards to the various outputs they may want to offer their API consumers. By this last statement, I mean…if there were 5 different “doc” output generators, 4 different Java SDK generators, 3 different Java server side generators (perhaps JAX-RS, Spring, etc), you could then “freely” pick which generators you’d want to use to build your final artifacts that you make available to consumers of your API.

Anyway, good to see new RAML output regardless of my opinion of it. Keep up the work regardless if you look to move to raml-generator or stay the course with what you are doing now.


#7

Hi Anton… I’ve downloaded it and tried and have some questions. Is this project still active? -Mark


#8

Hi Mark. Yes, this project is still active and we are planning add raml 1.0 support in future.