Generating static (offline) documentation for services' APIs

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.

+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

···

On Fri, Jul 22, 2016 at 3:47 PM, pnawrocki pnawrocki@soldevelo.com wrote:

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.

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+unsubscribe@googlegroups.com.

To post to this group, send email to openlmis-dev@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
djazayeri@thoughtworks.com

Telephone
+1 617 383 9369

ThoughtWorks

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

Rich

···

+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

On Fri, Jul 22, 2016 at 3:47 PM, pnawrocki pnawrocki@soldevelo.com wrote:

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.

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+unsubscribe@googlegroups.com.

To post to this group, send email to
openlmis-dev@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 Jazayeri* Principal Architect - Global Health*

Email

djazayeri@thoughtworks.com

Telephone

+1 617 383 9369

ThoughtWorks

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+unsubscribe@googlegroups.com.

To post to this group, send email to
openlmis-dev@googlegroups.com.

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

For more options, visit https://groups.google.com/d/optout.

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

api-definition.html (62.9 KB)

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

W dniu środa, 27 lipca 2016 11:27:03 UTC+2 użytkownik pnawrocki napisał:

···

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

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.

···

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

W dniu środa, 27 lipca 2016 11:27:03 UTC+2 użytkownik pnawrocki napisał:

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

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+unsubscribe@googlegroups.com.

To post to this group, send email to
openlmis-dev@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
.

For more options, visit https://groups.google.com/d/optout.