Generating static (offline) documentation for services' APIs

[pnawrocki]

Hello everyone.

I've been investigating the ways to generate a nice offline documentation for our APIs. We initially had two concepts:

First was to keep the same look as for our interactive docs, just hiding the interactive part (like "Try it" buttons). This way we would just publish what we already have generated for swagger, with some additional css/js applied to hide/remove interactive elements of the output document. Though, it is a document generated on the fly with js, so I don't know if this is what we actually want to have (regarding furher ReadTheDocs publishing).

Another approach is to use some dedicated generator to create a static document out of our raml. I've been searching for some libraries, and throughout my search the most popular and widely referenced was https://github.com/raml2html/raml2html, which can be easily installed through npm and then it is good to go. This by far also seems to be the most viable one, as it is easy to use within our actual environment and it still has active support (while most of those were just one-off individual projects).

It leaves out a singe html file with all css and scripting applied. It is nice-looking and easy to navigate, and can also take a custom template. This way, we would have one html file generated per service, so we could easily bundle them.

We firstly also considered http://raml2html.leanlabs.io/, which is also nice-looking, but this one is distributed as phar file which would make it far more problematic to make use out of it.

[Darius Jazayeri]

+1 to generating plain html REST API docs as part of our build/release pipeline.

I don't have any experience with specific tools, but if the wisdom of crowds points to raml2html, it's probably good enough for us.

-Darius

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/0902b724-bbef-41a8-ac9e-5be21678e3e9%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Darius JazayeriPrincipal Architect - Global Health

Email

djaz...@thoughtworks.com

Telephone

+1 617 383 9369

[Rich Magnuson]

Thanks Paweł.  Sounds quite promising.  Can you share an example of the HTML output against the RAML in the requisitions repo? 

 

Rich

To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/CAOKb-R5oFOCBS6ZTnyEZ1DjAPwpVqi80z%2BZcKDpegxH-x9zafw%40mail.gmail.com.

[pnawrocki]

Sure, here's how requisition's api looks like with the default template. We can also override any css or js.

[kkaczmarczyk]

Just a follow-up on this one - static API document is published on each Jenkins build under the filename: "api-definition.html". It is visible in the Artifacts section of each build

 

Direct link is quite long: http://build.openlmis.org/job/OpenLMIS-requisition-service/lastSuccessfulBuild/artifact/build/resources/main/api-definition.html

[Rich Magnuson]

Great, thank you.  One thing on my personal backlog is to update the “publish documentation” story so we can consolidate our API, ERD, style guide and any other doc via ReadTheDocs. 

 

From: openlm...@googlegroups.com [mailto:openlm...@googlegroups.com] On Behalf Of kkaczmarczyk
Sent: Tuesday, August 2, 2016 7:07 AM
To: OpenLMIS Dev <openlm...@googlegroups.com>
Cc: djaz...@thoughtworks.com; pnaw...@soldevelo.com
Subject: Re: [openlmis-dev] Generating static (offline) documentation for services' APIs

 

Just a follow-up on this one - static API document is published on each Jenkins build under the filename: "api-definition.html". It is visible in the Artifacts section of each build

--

You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/8f00901f-bc21-4256-8dee-4799269e13b8%40googlegroups.com.