[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: |
|
||||||||||||
| 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
|
| 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 |
| 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
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
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 |