[FOLIO-589] Provide alternative views of the API docs Created: 08/May/17  Updated: 18/May/21  Resolved: 18/May/21

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: New Feature Priority: P3
Reporter: David Crossley Assignee: David Crossley
Resolution: Done Votes: 0
Labels: devweb, doc, raml
Remaining Estimate: Not Specified
Time Spent: 2 days, 1 hour, 5 minutes
Original estimate: Not Specified

Sprint:
Development Team: Core: Platform

 Description   

We currently have the API docs automatically generated from the RAML files.
https://dev.folio.org/reference/api

This uses raml2html. There are useful improvements to that tool. However these are going into their v4+ versions (which is RAML-1.0 only). For the moment we need to stick with v3.x for RAML-0.8 version.

The raml2html does use a template system, so we could improve the presentation. However it might be easier to wait until we are back on the current version.

Some people prefer a presentation that uses a full html page for each api doc, rather than the pop-ups that default raml2html uses.

Provide alternative views using other tools. There are not many available.

Later settle on one or two of them, then enhance their templates.



 Comments   
Comment by David Crossley [ 08/May/17 ]

Updated the folio-infrastructure/generate-api-docs to also use raml-fleece.

John Malconian would you please update the server copy.
It has package.json and expects the tools to be in that local node_modules directory.
It uses the template in ./resources/raml-fleece/parameters.handlebars

Comment by John Malconian [ 10/May/17 ]

David Crossley Ok. I've updated the build image with the latest generate-api-docs directory contents and tested it on mod-inventory. Let me know if there are any issues.

Comment by David Crossley [ 10/May/17 ]

Thanks for your efforts with deploying that. It works successfully. Now to proceed to the other modules.

Comment by David Crossley [ 03/Sep/18 ]

For repositories that are now using RAML-1.0 version, the “view-2” presentation is not available because the "raml-fleece" software that is used to generate that view only supports RAML-0.8 version.

So either find some other suitable software, or investigate the template system of current raml2html (which generates the "view-1" set) to produce other views.

Comment by David Crossley [ 20/Nov/18 ]

Now using "raml2html-plain-theme" to generate the "view-2" (no pop-ups) for RAML-1.0 repositories. (The renewed front page will be presented after the cache updates for you.)

As explained in the Usage notes the "view-2" link will be active for each such repo after their next merge to master re-generates the docs.

Comment by David Crossley [ 11/Dec/18 ]

Using our folio-org fork of raml2html-plain-theme. So far only to show all resource-body divs. See folio-tools/pull/58

Generated at Thu Feb 08 23:06:54 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.