SHARE THIS ARTICLE

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:

Have questions? Submit a request.