At this moment only resourceTypes and traits can be parameterized. But with the concept of reusability it is also a good idea if we can have capability to parameterize DocumentationItem fragment which will give ability to create templates even for documentation.
Here is my usecase. I am writing APIs for business entities who just name of API, and resource name is different but rest all things are same. in such scenario rather than creating Documentation for each API it is good idea for me to create just DocumentationItem Fragment which has parameter say entity.
Below is example i am trying and at the moment we can not do it due to lack of capability.
If i include in documentation in raml with !include it replace entity with blank <>
#%RAML 1.0 DocumentationItem
title: <<entity>> API Explained
content: |
Like all other Core APIs, <<entity>> API allows 11 operations on the <<entity>> business entity
- Creating a new <<entity>>
- Deleting all of a subset of <<entity>>
- Fully updating all or a subset of <<entity | !pluralize>>s
- Partially updating all or a subset of <<entity | !pluralize>>
- Searching for <<entity | !pluralize>>
- Executing an action on all or a subset of <<entity | !pluralize>>
- Reading details of a <<entity>>
- Partially updating a <<entity>>
- Fully updating a <<entity>>
- Deleting a <<entity>>
- Executing an action on a <<entity>>
At this moment only resourceTypes and traits can be parameterized. But with the concept of reusability it is also a good idea if we can have capability to parameterize DocumentationItem fragment which will give ability to create templates even for documentation. Here is my usecase. I am writing APIs for business entities who just name of API, and resource name is different but rest all things are same. in such scenario rather than creating Documentation for each API it is good idea for me to create just DocumentationItem Fragment which has parameter say
entity. Below is example i am trying and at the moment we can not do it due to lack of capability.If i include in documentation in raml with !include it replace entity with blank <>