[FOLIO-1867] Spike: Investigate using interface and version in RAML, and correlate with ModuleDescriptor Created: 14/Mar/19 Updated: 03/Jun/20 Resolved: 26/Mar/19 |
|
| Status: | Closed |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | Task | Priority: | P3 |
| Reporter: | David Crossley | Assignee: | David Crossley |
| Resolution: | Done | Votes: | 0 |
| Labels: | platform-backlog, raml | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Attachments: |
|
||||||||
| Issue links: |
|
||||||||
| Sprint: | Core: Platform - Sprint 60, Core: Platform - Sprint 59 | ||||||||
| Story Points: | 1 | ||||||||
| Development Team: | Core: Platform | ||||||||
| Description |
|
As explained in
Also the filename of each RAML file does not necessarily match the interface name that it describes. Investigate adding an entry to the top-level RAML "documentation" node to declare the interface. In conjunction with the "version" this would enable "lint-raml-cop" and other tools to correlate that information with the ModuleDescriptor. Having this reliable information would also enable cross-reference documentation to refer to API documentation via interface names. |
| Comments |
| Comment by Oleksii Popov [ 18/Mar/19 ] |
|
David Crossley please provide an outcome of the spike:
|
| Comment by David Crossley [ 22/Mar/19 ] |
|
Adding some notes below, then description of the various pieces, then a demonstration ... |
| Comment by David Crossley [ 22/Mar/19 ] |
|
Yes we could enhance the lint-raml script to assess the ModuleDescriptor (the generate-api-docs script already does some, so utilise that code). One concern is that for maven-based modules, we can reliably find the MD in the "target" directory. For gradle-based modules, we need to be told where to find it. |
| Comment by David Crossley [ 22/Mar/19 ] |
|
Scanned our current set of raml-using repositories: |
| Comment by David Crossley [ 22/Mar/19 ] |
|
Some of the shared RAMLs in raml-util could cause some difficulties. |
| Comment by David Crossley [ 22/Mar/19 ] |
|
The optional baseUri node is very inconsistent in our RAML files. Also some actually have the "version" as a URI parameter. As far as i know, we do not utilise the "baseUri". Some RMB-based based modules enable the "local apidocs" application. They have a part of their POM file that replaces the baseUri. If they do have the "version" in their baseUri then it breaks that application. (See
Consider to standardise the baseUri. Perhaps as the root of localhost Okapi. Other applications can reliably transform that. |
| Comment by David Crossley [ 22/Mar/19 ] |
|
Describe the pieces ... 1) Add demo. (See below.) 2) Decide format for "version" in RAML files
3) Implement code in lint_raml_cop.py
4) Enhance dev.f.o docs to explain what is needed
5) Add content to each repo's RAML files
6) Gather metadata about RAMLs configuration from all RAML-based repos (to enable the next piece #7)
7) Provide a way at dev.f.o (and potentially via other places) to navigate API docs via "interface" name |
| Comment by David Crossley [ 22/Mar/19 ] |
|
Here is an example for patron-notice-policy.raml snippet, adding the new item to the top-level RAML documentation node mod-circulation-storage/ramls/patron-notice-policy.raml 1 #%RAML 1.0 2 title: Patron Notice Policies 3 version: 0.7 4 protocols: [ HTTP, HTTPS ] 5 baseUri: http://localhost:9130 6 7 documentation: 8 - title: Interface 9 content: patron-notice-policy-storage 10 - title: Patron Notice Policies API 11 content: Storage for Patron Notice Policies The addition of lines 8-9 documentation node entry, enables processing of the RAML file and matching "interface" and "version" with the MD. That also produces the generated documentation screenshot attached: |
| Comment by David Crossley [ 26/Mar/19 ] |
|
Added new tickets for all of the pieces described above. See linked issues of
|