[FOLIO-1767] Ensure that ModuleDescriptor and RAML files correlate for interface and version Created: 01/Feb/19  Updated: 05/Nov/21

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

Type: New Feature Priority: P3
Reporter: Julian Ladisch Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: platform-backlog, raml
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Blocks
is blocked by FOLIO-1908 Enhance lint-raml to process ModuleDe... Open
Relates
relates to FOLIO-1910 Provide example RAML file using "inte... Open
relates to FOLIO-1911 Enhance generate-api-docs to record m... Open
relates to FOLIO-1867 Spike: Investigate using interface an... Closed
relates to FOLIO-1909 Add dev doc guides/raml-interface-ver... Open
relates to FOLIO-1913 Provide cross-references to API docs ... Open
relates to RMB-41 ModuleDescriptor.json validation as u... Open
relates to OKAPI-1042 Replace MD routing entries with OpenA... Open
relates to FOLIO-1718 extending guidelines on versioning Blocked
Sprint:
Development Team: Core: Platform

 Description   

If patron-notice-policy.raml contains

#%RAML 1.0
title: Patron Notice Policies
version: v2.0
protocols: [ HTTP, HTTPS ]
baseUri: http://localhost:9130

and the module descriptor file contains

  "id": "patron-notice-policy-storage",
  "version": "2.3",

then lint-raml-cop should complain that there is a version mismatch because v2.0 and 2.3 are not the same version - the version line in patron-notice-policy.raml should be

version: v2.3

This reliable information can then also be utilised to provide better access to API documentation.

Acceptance criteria:
Missing or mis-matched information is reported by the lint-raml CI job.



 Comments   
Comment by David Crossley [ 01/Feb/19 ]

The "version" in the RAML files has not been utilised consistently, and is currently not useful.

Also the "lint-raml" tool does not assess the ModuleDescriptor.

One possibility that Adam and i discussed briefy at Malaga get-together, is to utilise a "document" node in the RAML file to declare the interfaces and versions to which each RAML file pertains.

Comment by Julian Ladisch [ 04/Feb/19 ]

The "version" string in the RAML file is shown as version on view-1 and view-2 on https://dev.folio.org/reference/api/
The "version" string is optional: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#the-root-of-the-document
The "version" string should be correct or left out.

Comment by Oleksii Popov [ 13/Mar/19 ]

David Crossley please prepare related spike.

Comment by David Crossley [ 25/Mar/19 ]

Refer to FOLIO-1867 Closed "Spike: Investigate using interface and version in RAML, and correlate with ModuleDescriptor".

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