Open blakeembrey opened 8 years ago
How does the client generator library know that the annotation belongs to the library? There's some possible approaches
Not really understand what you mean?
What part doesn't make sense? Take this example:
uses:
client: !include ../node_modules/raml-generator/annotations.raml
otherlibrary: !include ../someotherlibrary/annotations.raml
/users:
get:
(client.methodName): getUsers
(otherlibrary.methodName): Hello World
How does one know which method name is mine (as in, from the client generator)? Is this seen as an issue?
Well, this question basically has two different aspects: parser one and spec one.
Parser aspect: how to know which file annotation comes from. This is doable right now, but is not lying on a top-level. First you need to find annotation declaration one way or another. Will be simplified at Monday release when each annotation reference will have a method returning related annotation declaration node (one of the obvious benefits of having full-functional AST compared to the old JSON that we can actually provide that kind of functionality). Then, having annotation declaration node at hands you may descend to its low-level and ask a unit and its path thus identifying the path, the file comes from. If this is something, which will be often needed by the users, we may consider exposing this functionality at top-level.
Spec aspect: you have file path. Does this allow library identification? I don't think so. Besides file paths we have no real way of library identification right now. This is something purely spec-related.
Summarizing the wall of text above: 1) now you can find, which file annotation belongs to, in several calls. Soon it will be easier, can be simplified even more if needed. 2) File path is the closest thing we have to library identifiers. Introducing real identifiers is better, requires spec change.
How would one go about verifying that an annotation in a RAML document is from an annotation I created as a third-party? For example:
I am writing an API client generator and want to provide a library of annotations types that I use in a "standardized" way. One of these annotation types is called
methodName
and is of typestring
. To use this, I import the annotations types into my document and start typing:Now, I've added method names to my API (perhaps in an overlay file) and want to generate the API client. How does the client generator library know that the annotation belongs to the library? There's some possible approaches:
Naive:
The library just checked that the annotation type ends in
methodName
. For example:/(?:^|\.)methodName$/.test(annotationName)
.Pros:
Cons:
Prescriptive:
As the library author, I tell you that you must import it using a specific name. E.g.
uses: ⏎client: !include ...
(must be calledclient
in this case).Pros:
Cons:
Location:
As a library author, I tell you that you must import from my library. The module checks the location of the original annotation type and uses that as the identifier. E.g.
annotation.getLocation() === join(__dirname, '../annotations.raml')
.Pros:
Cons: