[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: PNG File output.png    
Issue links:
Relates
relates to FOLIO-1767 Ensure that ModuleDescriptor and RAML... Open
Sprint: Core: Platform - Sprint 60, Core: Platform - Sprint 59
Story Points: 1
Development Team: Core: Platform

 Description   

As explained in FOLIO-1767 Open , the "version" node in RAML files is currently poorly utilised. That also leads to confusion in the generated API documentation.

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:

  • create related issues
  • link to this 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:
The filename does not necessarily match the interface name.
There are no situations where two interfaces are described in a single RAML file.
Mostly there is a one-to-one mapping, but for some there are multiple RAML files to describe various parts.

Comment by David Crossley [ 22/Mar/19 ]

Some of the shared RAMLs in raml-util could cause some difficulties.
Perhaps configure a list to avoid or enable special processing.

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 RMB-18 Closed , FOLIO-602 Open , RMB-280 Closed , and related tickets.)

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

  • Probably "0.7" rather than "v0.7"
  • The RAML Spec does not have constraints for "version".

3) Implement code in lint_raml_cop.py

  • Parse MD with jq to extract list of "interface" name and "version" pairs for this repo.
  • Extract "interface" name and "version" pairs from each RAML file and match with MD.
  • Trouble finding MD for Gradle-based repos (see note above).

4) Enhance dev.f.o docs to explain what is needed

  • Link from Jenkins error message to that doc section.

5) Add content to each repo's RAML files

  • See list of raml-based repos in the API Docs table and api.yml data file (Do: yq 'keys[]' $GH_FOLIO/folio-org.github.io/_data/api.yml | sed 's/"//g'
  • Commit some complete examples, e.g. mod-circulation-storage/ramls/patron-notice-policy.raml

6) Gather metadata about RAMLs configuration from all RAML-based repos (to enable the next piece #7)

  • The website Jekyll Liquid code needs to be efficient, so requires a pre-prepared up-to-date data file.
  • At present the generate-api-docs job does generate and deploy a basic metadata file (config.json) for each module each time (which is not yet utilised).
  • Perhaps a separate Jenkins job to gather and consolidate.

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 FOLIO-1767 Open .

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