<!-- 
RSS generated by JIRA (1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d) at Thu Feb 08 23:16:29 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary add field=key&field=summary to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>FOLIO Jira</title>
    <link>https://folio-org.atlassian.net</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>1001.0.0-SNAPSHOT</version>
        <build-number>100246</build-number>
        <build-date>07-02-2024</build-date>
    </build-info>

<item>
            <title>[FOLIO-1867] Spike: Investigate using interface and version in RAML, and correlate with ModuleDescriptor</title>
                <link>https://folio-org.atlassian.net/browse/FOLIO-1867</link>
                <project id="10290" key="FOLIO">FOLIO</project>
                    <description>&lt;p&gt;As explained in 
    &lt;span class=&quot;jira-issue-macro&quot; data-jira-key=&quot;FOLIO-1767&quot; &gt;
                &lt;a href=&quot;https://folio-org.atlassian.net/browse/FOLIO-1767&quot; class=&quot;jira-issue-macro-key issue-link&quot;  title=&quot;Ensure that ModuleDescriptor and RAML files correlate for interface and version&quot; &gt;
            &lt;img class=&quot;icon&quot; src=&quot;https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10322?size=medium&quot; /&gt;
            FOLIO-1767
        &lt;/a&gt;
                                                    &lt;span class=&quot;aui-lozenge aui-lozenge-subtle aui-lozenge-complete jira-macro-single-issue-export-pdf&quot;&gt;Open&lt;/span&gt;
            &lt;/span&gt;
, the &quot;version&quot; node in RAML files is currently poorly utilised. That also leads to confusion in the generated API documentation.&lt;/p&gt;

&lt;p&gt;Also the filename of each RAML file does not necessarily match the interface name that it describes.&lt;/p&gt;

&lt;p&gt;Investigate adding an entry to the top-level RAML &quot;documentation&quot; node to declare the interface. In conjunction with the &quot;version&quot; this would enable &quot;lint-raml-cop&quot; and other tools to correlate that information with the ModuleDescriptor.&lt;/p&gt;

&lt;p&gt;Having this reliable information would also enable cross-reference documentation to refer to API documentation via interface names.&lt;/p&gt;</description>
                <environment></environment>
        <key id="81025">FOLIO-1867</key>
            <summary>Spike: Investigate using interface and version in RAML, and correlate with ModuleDescriptor</summary>
                <type id="10003" iconUrl="https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium">Task</type>
                                            <priority id="10002" iconUrl="https://dev.folio.org/assets/jira-priority/jira-p3.svg">P3</priority>
                        <status id="6" iconUrl="https://folio-org.atlassian.net/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="green"/>
                                    <resolution id="10003">Done</resolution>
                                                        <assignee accountid="61cd0ca0bce5e00069e98be7">David Crossley</assignee>
                                                                <reporter accountid="61cd0ca0bce5e00069e98be7">David Crossley</reporter>
                                    <labels>
                            <label>platform-backlog</label>
                            <label>raml</label>
                    </labels>
                <created>Thu, 14 Mar 2019 03:23:40 +0000</created>
                <updated>Wed, 3 Jun 2020 16:39:36 +0000</updated>
                            <resolved>Tue, 26 Mar 2019 06:27:43 +0000</resolved>
                                                                        <due></due>
                            <votes>0</votes>
                                    <watches>3</watches>
                                                                <comments>
                                                            <comment id="192356" author="5c10cd488ce9b546efc4d9c4" created="Mon, 18 Mar 2019 14:11:29 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=61cd0ca0bce5e00069e98be7&quot; class=&quot;user-hover&quot; rel=&quot;61cd0ca0bce5e00069e98be7&quot; data-account-id=&quot;61cd0ca0bce5e00069e98be7&quot; accountid=&quot;61cd0ca0bce5e00069e98be7&quot; rel=&quot;noreferrer&quot;&gt;David Crossley&lt;/a&gt; please provide an outcome of the spike:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;create related issues&lt;/li&gt;
	&lt;li&gt;link to this spike&lt;/li&gt;
&lt;/ul&gt;
</comment>
                                                            <comment id="192358" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 06:36:04 +0000"  >&lt;p&gt;Adding some notes below, then description of the various pieces, then a demonstration ...&lt;/p&gt;</comment>
                                                            <comment id="192360" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 06:36:35 +0000"  >&lt;p&gt;Yes we could enhance the lint-raml script to assess the ModuleDescriptor (the generate-api-docs script already does some, so utilise that code).&lt;/p&gt;

&lt;p&gt;One concern is that for maven-based modules, we can reliably find the MD in the &quot;target&quot; directory. For gradle-based modules, we need to be told where to find it.&lt;/p&gt;</comment>
                                                            <comment id="192361" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 06:37:08 +0000"  >&lt;p&gt;Scanned our current set of raml-using repositories:&lt;br/&gt;
The filename does not necessarily match the interface name.&lt;br/&gt;
There are no situations where two interfaces are described in a single RAML file.&lt;br/&gt;
Mostly there is a one-to-one mapping, but for some there are multiple RAML files to describe various parts.&lt;/p&gt;</comment>
                                                            <comment id="192363" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 06:38:44 +0000"  >&lt;p&gt;Some of the shared RAMLs in &lt;a href=&quot;https://dev.folio.org/reference/api/#raml&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;raml-util&lt;/a&gt; could cause some difficulties.&lt;br/&gt;
Perhaps configure a list to avoid or enable special processing.&lt;/p&gt;</comment>
                                                            <comment id="192365" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 06:51:14 +0000"  >&lt;p&gt;The optional &lt;a href=&quot;https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#base-uri-and-base-uri-parameters&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;baseUri node&lt;/a&gt; is very inconsistent in our RAML files. Also some actually have the &quot;version&quot; as a URI parameter.&lt;/p&gt;

&lt;p&gt;As far as i know, we do not utilise the &quot;baseUri&quot;.&lt;/p&gt;

&lt;p&gt;Some RMB-based based modules enable the &quot;local apidocs&quot; application. They have a part of their POM file that replaces the baseUri. If they do have the &quot;version&quot; in their baseUri then it breaks that application. (See 
    &lt;span class=&quot;jira-issue-macro resolved&quot; data-jira-key=&quot;RMB-18&quot; &gt;
                &lt;a href=&quot;https://folio-org.atlassian.net/browse/RMB-18&quot; class=&quot;jira-issue-macro-key issue-link&quot;  title=&quot;The &amp;quot;local apidocs&amp;quot; for &amp;quot;admin&amp;quot; and &amp;quot;jobs&amp;quot; has extra &amp;quot;/v1/&amp;quot; in path&quot; &gt;
            &lt;img class=&quot;icon&quot; src=&quot;https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10303?size=medium&quot; /&gt;
            RMB-18
        &lt;/a&gt;
                                                    &lt;span class=&quot;aui-lozenge aui-lozenge-subtle aui-lozenge-success jira-macro-single-issue-export-pdf&quot;&gt;Closed&lt;/span&gt;
            &lt;/span&gt;
, 
    &lt;span class=&quot;jira-issue-macro&quot; data-jira-key=&quot;FOLIO-602&quot; &gt;
                &lt;a href=&quot;https://folio-org.atlassian.net/browse/FOLIO-602&quot; class=&quot;jira-issue-macro-key issue-link&quot;  title=&quot;Use consistent RAML baseUri parameter&quot; &gt;
            &lt;img class=&quot;icon&quot; src=&quot;https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium&quot; /&gt;
            FOLIO-602
        &lt;/a&gt;
                                                    &lt;span class=&quot;aui-lozenge aui-lozenge-subtle aui-lozenge-complete jira-macro-single-issue-export-pdf&quot;&gt;Open&lt;/span&gt;
            &lt;/span&gt;
, 
    &lt;span class=&quot;jira-issue-macro resolved&quot; data-jira-key=&quot;RMB-280&quot; &gt;
                &lt;a href=&quot;https://folio-org.atlassian.net/browse/RMB-280&quot; class=&quot;jira-issue-macro-key issue-link&quot;  title=&quot;Provide a POM snippet to configure local apidocs&quot; &gt;
            &lt;img class=&quot;icon&quot; src=&quot;https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10303?size=medium&quot; /&gt;
            RMB-280
        &lt;/a&gt;
                                                    &lt;span class=&quot;aui-lozenge aui-lozenge-subtle aui-lozenge-success jira-macro-single-issue-export-pdf&quot;&gt;Closed&lt;/span&gt;
            &lt;/span&gt;
, and related tickets.)&lt;/p&gt;

&lt;p&gt;Consider to standardise the baseUri. Perhaps as the root of localhost Okapi. Other applications can reliably transform that.&lt;/p&gt;</comment>
                                                            <comment id="192367" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 07:14:24 +0000"  >&lt;p&gt;Describe the pieces ...&lt;/p&gt;

&lt;p&gt;1) Add demo. (See below.)&lt;/p&gt;

&lt;p&gt;2) Decide format for &quot;version&quot; in RAML files&lt;/p&gt;
&lt;ul class=&quot;alternate&quot; type=&quot;square&quot;&gt;
	&lt;li&gt;Probably &quot;0.7&quot; rather than &quot;v0.7&quot;&lt;/li&gt;
	&lt;li&gt;The RAML Spec does not have constraints for &quot;&lt;a href=&quot;https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#base-uri-and-base-uri-parameters&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;version&lt;/a&gt;&quot;.&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;3) Implement code in lint_raml_cop.py&lt;/p&gt;
&lt;ul class=&quot;alternate&quot; type=&quot;square&quot;&gt;
	&lt;li&gt;Parse MD with jq to extract list of &quot;interface&quot; name and &quot;version&quot; pairs for this repo.&lt;/li&gt;
	&lt;li&gt;Extract &quot;interface&quot; name and &quot;version&quot; pairs from each RAML file and match with MD.&lt;/li&gt;
	&lt;li&gt;Trouble finding MD for Gradle-based repos (see note above).&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;4) Enhance dev.f.o docs to explain what is needed&lt;/p&gt;
&lt;ul class=&quot;alternate&quot; type=&quot;square&quot;&gt;
	&lt;li&gt;Link from Jenkins error message to that doc section.&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;5) Add content to each repo&apos;s RAML files&lt;/p&gt;
&lt;ul class=&quot;alternate&quot; type=&quot;square&quot;&gt;
	&lt;li&gt;See list of raml-based repos in the &lt;a href=&quot;https://dev.folio.org/reference/api/&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;API Docs table&lt;/a&gt; and &lt;a href=&quot;https://dev.folio.org/reference/api/#configure-api-docs&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;api.yml data file&lt;/a&gt; (Do: yq &apos;keys[]&apos; $GH_FOLIO/folio-org.github.io/_data/api.yml | sed &apos;s/&quot;//g&apos;&lt;/li&gt;
	&lt;li&gt;Commit some complete examples, e.g. mod-circulation-storage/ramls/patron-notice-policy.raml&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;6) Gather metadata about RAMLs configuration from all RAML-based repos (to enable the next piece #7)&lt;/p&gt;
&lt;ul class=&quot;alternate&quot; type=&quot;square&quot;&gt;
	&lt;li&gt;The website Jekyll Liquid code needs to be efficient, so requires a pre-prepared up-to-date data file.&lt;/li&gt;
	&lt;li&gt;At present the generate-api-docs job does generate and deploy a basic metadata file (&lt;a href=&quot;https://s3.amazonaws.com/foliodocs/api/mod-circulation-storage/config.json&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;config.json&lt;/a&gt;) for each module each time (which is not yet utilised).&lt;/li&gt;
	&lt;li&gt;Perhaps a separate Jenkins job to gather and consolidate.&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;7) Provide a way at dev.f.o (and potentially via other places) to navigate API docs via &quot;interface&quot; name&lt;/p&gt;</comment>
                                                            <comment id="192370" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 07:31:08 +0000"  >&lt;p&gt;Here is an example for patron-notice-policy.raml snippet, adding the new item to the top-level &lt;a href=&quot;https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#user-documentation&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;RAML documentation node&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;mod-circulation-storage/ramls/patron-notice-policy.raml&lt;/p&gt;
&lt;div class=&quot;code panel&quot; style=&quot;border-width: 1px;&quot;&gt;&lt;div class=&quot;codeContent panelContent&quot;&gt;
&lt;pre class=&quot;code-java&quot;&gt;
  1 #%RAML 1.0
  2 title: Patron Notice Policies
  3 version: 0.7
  4 protocols: [ HTTP, HTTPS ]
  5 baseUri: http:&lt;span class=&quot;code-comment&quot;&gt;//localhost:9130
&lt;/span&gt;  6 
  7 documentation:
  8   - title: Interface
  9     content: patron-notice-policy-storage
 10   - title: Patron Notice Policies API
 11     content: Storage &lt;span class=&quot;code-keyword&quot;&gt;for&lt;/span&gt; Patron Notice Policies
&lt;/pre&gt;
&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The addition of lines 8-9 documentation node entry, enables processing of the RAML file and matching &quot;interface&quot; and &quot;version&quot; with the MD. That also produces the generated documentation screenshot attached:&lt;br/&gt;
&lt;span class=&quot;image-wrap&quot; style=&quot;&quot;&gt;&lt;img src=&quot;/rest/api/3/attachment/content/64159&quot; style=&quot;border: 0px solid black&quot; /&gt;&lt;/span&gt;&lt;/p&gt;</comment>
                                                            <comment id="192373" author="61cd0ca0bce5e00069e98be7" created="Tue, 26 Mar 2019 06:27:43 +0000"  >&lt;p&gt;Added new tickets for all of the pieces described above. See linked issues of 
    &lt;span class=&quot;jira-issue-macro&quot; data-jira-key=&quot;FOLIO-1767&quot; &gt;
                &lt;a href=&quot;https://folio-org.atlassian.net/browse/FOLIO-1767&quot; class=&quot;jira-issue-macro-key issue-link&quot;  title=&quot;Ensure that ModuleDescriptor and RAML files correlate for interface and version&quot; &gt;
            &lt;img class=&quot;icon&quot; src=&quot;https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10322?size=medium&quot; /&gt;
            FOLIO-1767
        &lt;/a&gt;
                                                    &lt;span class=&quot;aui-lozenge aui-lozenge-subtle aui-lozenge-complete jira-macro-single-issue-export-pdf&quot;&gt;Open&lt;/span&gt;
            &lt;/span&gt;
.&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10003">
                    <name>Relates</name>
                                                                <inwardlinks description="relates to">
                                        <issuelink>
            <issuekey id="79466">FOLIO-1767</issuekey>
        </issuelink>
                            </inwardlinks>
                                    </issuelinktype>
                    </issuelinks>
                <attachments>
                            <attachment id="64159" name="output.png" size="104455" author="61cd0ca0bce5e00069e98be7" created="Fri, 22 Mar 2019 07:14:50 +0000"/>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10000" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummarycf">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10057" key="com.atlassian.jira.plugin.system.customfieldtypes:select">
                        <customfieldname>Development Team</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10144"><![CDATA[Core: Platform]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_10019" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>0|hzzion:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_10020" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="1418">Core: Platform - Sprint 60</customfieldvalue>
    <customfieldvalue id="1149">Core: Platform - Sprint 59</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                            <customfield id="customfield_10044" key="com.atlassian.jira.plugin.system.customfieldtypes:float">
                        <customfieldname>Story Points</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>1.0</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10024" key="com.atlassian.jira.ext.charting:firstresponsedate">
                        <customfieldname>[CHART] Date of First Response</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>Mon, 18 Mar 2019 14:11:29 +0000</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10025" key="com.atlassian.jira.ext.charting:timeinstatus">
                        <customfieldname>[CHART] Time in Status</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                    </customfields>
    </item>
</channel>
</rss>