Skip to main content

APIMatic RAML Annotations

RAML v1.0 supports annotations that provide a mechanism to extend the API specification with metadata beyond the one supported by its official specification. APIMatic allows its users to extend their specification with annotations that can help configure output from APIMatic products such as API Transformer, Code Generation, Portal/Docs Generation etc.

Before you can use annotations in your API specification, you must also add a declaration for them in the root-level annotationTypes node as per the spec. For each annotation that we provide, this document will also provide you details about the declaration to be added.

The annotations offered by APIMatic are listed below:

  1. Role-Based Access Annotations
  2. File Input Annotation

Role-Based Access Annotations#

APIMatic supports role-based API filtering. If you choose to filter your API by roles, the resulting portal will only contain documentation for those endpoints available to the specific role(s). It works by matching endpoint-level tags with tags associated with the available roles.

Roles can be defined in the RAML specification using the roles annotation in the root RAML object while method-level tags can be added through the tags annotation.

Annotation for Roles#

To describe the possible list of roles for an API, the roles annotation can be used.

Annotation Type Declaration#

To apply this annotation, you will first have to declare it under the annotationTypes root node as follows:

annotationTypes:
roles:
type: array
items:
type: object
properties:
id:
required: true
type: string
name:
required: false
type: string
description:
required: false
type: string
tags:
required: true
type: array
items:
type: string

Details of the properties available within a particular role object are:

PropertyTypePurpose
namestringName of the role.
idstringUnique identifier of the role.
descriptionstringProvides more details about the role.
tagsList[string]List of String-valued tags associated with the role.

Example Usage for Annotation#

An example of applying roles annotation at the root RAML object is:

(roles):
- name: private
id: 2
description: private role
tags:
- pets

This means that role with id 2 will only have access to methods tagged as pets.

Annotation for Method level tags#

Tags can be added to methods as a list of strings.

Annotation Type Declaration#

To apply the tags annotation anywhere in your specification, you will first have to declare it under the annotationTypes root node as follows:

annotationTypes:
tags:
type: array
items:
type: string

Example Usage for Annotation#

You can apply this annotation at method level as follows:

/pet/{id}:
get:
(tags):
- pets
displayName: Get pet by id

File Input Annotation#

By default, file type request parameters are considered part of multipart/form-data in APIMatic. If, however, you are looking to send the file directly as part of the request body then this default behavior in APIMatic can be overriden by using the boolean sendFileInBody annotation at method level.

Annotation Type Declaration#

To use this annotation, you will first have to declare it under the annotationTypes root node as follows:

annotationTypes:
sendFileInBody:
type: boolean

Example Usage for Annotation#

The annotation can be applied at method level as shown below:

/file:
post:
(sendFileInBody): true
body:
binary/octet-stream: