RAML v1.0: Annotations - jdiegodcp/ramlfications GitHub Wiki
Annotations
Related issues:
Broad Implementation TODOs
- Parse similar to
ResourceType
andTraits
with own object, applying to resources, data types, resource types, traits, methods - When handling the assignment of annotations, must parse via strings within parenthesis, e.g.
(foo)
- Declaration handled in the root of the API definition
Validation
When extending ramlfications/validation.py
, be sure to check:
- Appropriate file headers of either
#%RAML 1.0
or#%RAML 1.0 AnnotationTypeDeclaration
- Annotations are not inherited when applied to Data Types
- All annotations must be declared in the the API root of the RAML file within
annotationTypes
property - If
allowedTargets
property is present in the declaration of the annotation, annotations then can only be assigned to those particular targets (e.g. traits, body, etc). This requires validation of objects that have applied annotations, not just the validation of the annotation itself - Valid assigned targets:
Where to start
These are educated suggestions, and more meant for developers unfamiliar with the ramlfications
package and are wanting to contribute.
- A new
Annotation
object should probably be defined inramlfications/raml.py
parsed from the API root-levelannotationTypes
in the RAML file - A property called
annotation_types
attached to the Root Node, which holds a list ofAnnotation
objects - A property called
annotation_name
should be supported in the following objects:- Within
ramlfications/raml.py
:- Root node (in
ramlfications/raml.py
) - Resource node (supporting both resource-level annotations as well as a method-level annotations)
- Resource type node
- Trait node
- Data Type (see issue 69)
- Annotation (an annotation can be annotated)
- Root node (in
- Within
ramlfications/parameters.py
- Within
- In
ramlfications/parser.py
, there should be a function that creates all annotations defined in the provided RAML file (including any external RAML files that are declared via!include
), and be called from withinparse_raml
function - Apply the validation rules/checks within
ramlfications/validate.py
- Not sure if
ramlfications/loader.py
should be affected in any way; perhaps if we want to do anything special with the file header of#%RAML 1.0 AnnotationTypeDeclaration
- Annotations are inherited/applied to the endpoint when assigned within a Resource Type or Trait
- Annotations assigned in a Trait are applied to all methods of a Resource that is assigned that Trait
- Resource-level annotation values will overwrite any annotation values inherited from an assigned Resource Type and/or Trait
- Similarly, Resource Type annotations overwrite Trait annotations when applied to a Resource Type or Resource
- Tests! Documentation!
Some examples (I think most of them are only RAML 0.8
right now) for testing and debugging can be found here.
Proposed API behavior
TODO