[FOLIO-523] Decide if FOLIO should enable using RAML 1.0 Created: 28/Mar/17  Updated: 12/Nov/18  Resolved: 27/Sep/18

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

Type: Task Priority: P3
Reporter: Marc Johnson Assignee: Unassigned
Resolution: Done Votes: 0
Labels: raml
Remaining Estimate: Not Specified
Time Spent: 2 hours, 20 minutes
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-573 Use a consistent method for RAML to r... Closed
relates to RMB-109 RAML 1.0 support: use raml-for-jax-rs... Closed
Sprint:

 Description   

The possibility of FOLIO upgrading to use RAML 1.0 has been raised a couple of times recently.

What are the consequences of upgrading?

What needs to be changed in order to accomplish the upgrade?

Is it worth doing at this time?



 Comments   
Comment by Jakub Skoczen [ 28/Mar/17 ]

I think the question is if the tooling we use already supports 1.0 (raml2jaxrs, the api viewer, etc). Can shale99 confirm that? If so I think we can initiate the migration process.

Comment by David Crossley [ 28/Mar/17 ]

It is only recently that raml-js-parser-2 (i.e. npm raml-1-parser) does. So tools such as raml-cop and raml2html should now be okay.

Comment by David Crossley [ 29/Mar/17 ]

Some investigation:

Our main use is for our raml-module-builder which currently uses raml-for-jax-rs 1.3.4

Their milestone-2.0.0 indicates end-March for GA.

Presumably we could move to that when it settles, continue to use RAML-0.8, and upgrade our RAMLs gradually.

Of course, shale99 is the one to indicate when ready.

Comment by David Crossley [ 29/Mar/17 ]

We also use raml-tester 0.8.7 (current is 0.8.13) in okapi-core and mod-auth tests.

Its development version uses raml-parser-2 (i.e. raml-java-parser) as does raml-for-jax-rs.

This page lists the state of 1.0 support by raml-tester.

Comment by David Crossley [ 27/Apr/17 ]

The raml-for-jax-rs 2.0.0 version was released last week.

Comment by David Crossley [ 27/Apr/17 ]

See notes in FOLIO-573 Closed regarding the effects of JSON schema references.

Comment by Hongwei Ji [ 15/Nov/17 ]

It would be nice if we can support RAML 1.0 sooner than later (unless someone is thinking to switch to Swagger ). People who follow the raml.org tutorials will more likely create 1.0 files not 0.8. As David Crossley mentioned, the raml-for-jax-rs that supports 1.0 has been released for a while. https://github.com/mulesoft-labs/raml-for-jax-rs/releases

Comment by Khalilah Gambrell [ 25/May/18 ]

Jakub Skoczen any update on when Folio will move to RAML 1.0? eHoldings app is beginning to generate documentation and it is preferred we use RAML 1.0. Any info on a timeframe and thoughts on when/if we can proceed with leveraging RAML 1.0 is appreciated.

Comment by David Crossley [ 26/May/18 ]

(Some context for that – various discussion had erupted on the slack#development channel.)

Please see the comments above in this FOLIO-523 Closed .

RAML is a fundamental part of our system. When our tools are proven ready, especially those that underpin our RAML Module Builder (RMB), then it is time to plan and begin the move. As explained above, we should be able to use both, and gradually upgrade.

RAML is not just used for "generating documentation".

Comment by David Crossley [ 26/May/18 ]

I have modified the title of this issue to remove the words "API documentation" as that term means more than just generated documentation: Was "Decide if FOLIO should use RAML 1.0 instead of 0.8 for API Documentation" and now "Decide if FOLIO should enable using RAML 1.0"

Comment by David Crossley [ 26/May/18 ]

Regarding the generation of the documentation from the RAML files:

Until now our tool (see FOLIO-1253 In Progress and related) has only needed to deal with RAML-0.8 version.

It can be enhanced to use a specific newer version of its underlying raml2html library, depending on the input RAML file.

Until then, the mod-kb-ebsco which only intends to use RAML for generated documentation, would need to either use RAML-0.8 (it is easy to upgrade later) or turn off the "publishAPI" CI job in its Jenkinsfile.

Comment by David Crossley [ 26/May/18 ]

Regarding other external tools to validate the RAML files, the "raml-cop" already handles either version.

Comment by Adam Dickmeiss [ 27/Sep/18 ]

Yes. We are switching to RAML 1.0

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