How to find the declaration of an object type's property in the Nominal Type System?
nkuehn opened this issue · comments
I build a documentation generator directly on RAML using this parser to enable live-preview while editing your RAMLs.
To see all properties of an Object Type (including those inherited from Supertypes) I use the Nominal Type System (e.g. calling Api.types().map(t=>t.runtimeDefinition())). It's great and what we want to document - just the final effective data structure.
it's great until you want to document things like
- a Number's
format - an Array's
minItems - a String's
patternorenum - etc.
of an Object's properties
As far as the documentation of the parser concerns all these and many more are only available on the type declarations, but not directly in the Nominal IProperty. To me it looks like I have to iterate over the Type's superTypes(), then find their declaration by Name directly in Api.types(), and then hope that I really caught the right property declaration on the right parent.
That feels pretty wrong to me and totally against the Idea of the Nominal Type System. I dug a bit in the sources of the underlying Type System repository but came to the preliminary conclusion once the Definition (Nominal) is built, there is no way back to the originating Declaration and that the Nominal Type in fact does not provide all this detail information
Is there an intended (or at least somehow working but not documented) way to get these pieces of information for an inherited Property of an Object Type in the Nominal Type System?
Thanks so much!
Note that raml-js-parser-2 has been deprecated, the new official parser is webapi-parcser. Feel free to give it a try and report any issue you may have on that repository.
Hi, my understanding from its documentation and examples is that the new AMF based parser does not provide a runtime model (called nominal type system) with all type inheritance, traits etc. "flattened" - but that is rather a question for that repository and offtopic here. Knowing the effective API surface is what we mainly need from a parser.
@nkuehn does this guide help? https://raml-org.github.io/webapi-parser/resolving.html
And this example: https://github.com/raml-org/webapi-parser/blob/master/examples/js/raml10-model-navigation.js
Yes, thanks! I did obviously not expect what I was looking for under the name "resolve". I guess it's because I was too primed by the "runtime" and "nominal" wording in this (previous) parser implementation.
Good. Then I'm closing this issue for now. Feel free to ask more questions in webapi-parser repo.