[FOLIO-3541] JSON Schema extension attributes are omitted from generated documentation Created: 20/Jul/22 Updated: 27/Jul/22 Resolved: 27/Jul/22 |
|
| Status: | Closed |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | Story | Priority: | TBD |
| Reporter: | Zak Burke | Assignee: | David Crossley |
| Resolution: | Done | Votes: | 0 |
| Labels: | None | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Issue links: |
|
||||||||
| Sprint: | DevOps Sprint 144, DevOps Sprint 145 | ||||||||
| Development Team: | FOLIO DevOps | ||||||||
| RCA Group: | TBD | ||||||||
| Description |
|
Summary: Documentation generated from JSON schemas does not include our schema-extending keywords related to mod-graphql. Details: mod-graphql uses several JSON Schema extension keywords that are leveraged by modules (e.g. mod-inventory-storage). These fields may behave differently than other fields in an API response (e.g. a field with "folio:isVirtual": true will not be populated) but there is no way to know this because the extension keywords are not present. This omission caused quite a lot of confusion among SMEs and developers who were familiar with the generated API documentation for mod-inventory-storage but not the JSON schema files it derives from. Expected behavior: All attributes that affect a field's behavior are included in documentation derived from its JSON schema (.json) files. Actual behavior: Some attributes are omitted, including all folio:* attributes. CC: Mike Taylor, Marc Johnson |
| Comments |
| Comment by David Crossley [ 21/Jul/22 ] |
|
One example of this documentation lack is here. Scroll down a little to "permanentLocation". Note that its "location.json" schema has not been expanded (dereferenced). Whereas for the "permanentLocationId" just above it, the "uuid.json" schema has been properly dereferenced. This is the relevant section of the holdingsrecord.json schema:
"permanentLocationId": {
"type": "string",
"description": "The permanent shelving location in which an item resides.",
"$ref" : "uuid.json"
},
"permanentLocation": {
"description": "The permanent shelving location in which an item resides",
"type": "object",
"folio:$ref": "location.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "locations",
"folio:linkFromField": "permanentLocationId",
"folio:linkToField": "id",
"folio:includedElement": "locations.0"
},
The difference is in how the "$ref" is declared. When the "api-doc" tool processes that RAML file, it utilises json-schema-ref-parser to dereference the schemas beforehand. This is the relevant section of api-doc, where it calls our deref-schema.js nodejs script. I presume that it does not recognise the "folio:$ref" but does handle the normal "$ref" pointer. Mike Taylor – Would it be possible for mod-graphql to use the normal "$ref" instead? I did search the repo and found Adam's note in doc/fixing-schema-collisions.txt wondering about the same. If not, then would someone (e.g. Mike Taylor or Zak Burke) please assist to enhance our deref-schema.js to handle the "folio:$ref" pointers. My JS skills are minimal. |
| Comment by David Crossley [ 23/Jul/22 ] |
|
Hooray, i found a solution. The api-doc Python tool will scan all of a repository's JSON Schema files and temporarily replace with "$ref" before processing to generate each API documentation. (It will take some time to roll out to the Jenkins CI, as we need to rebuild its docker image.) |
| Comment by David Crossley [ 27/Jul/22 ] |
|
This is now deployed to Jenkins CI. The mod-inventory-storage API documentation is now regenerated and published with this fix. Note that this applies universally. So for any other repository that would utilise the "folio:$ref" style of schema references, this is handled for their API documentation purpose. |
| Comment by Marc Johnson [ 27/Jul/22 ] |
Thanks, this is a neat solution |