Added annotations to reflect OpenAPI 2.0 properties

annotations/openapi/README.md

@@ -0,0 +1,9 @@
+# Standard RAML annotations defined for OAS 2.0
+
+> This directory contains a set of standard annotations that represent pieces of OpenAPI Specification (OAS) properties that are not directly supported by the RAML 1.0 specification.
+
+## Tools
+
+The following tools are already using these annotions.
+
+* [oas-raml-converter](https://github.com/mulesoft/oas-raml-converter)

annotations/openapi/oas-annotations.raml

@@ -0,0 +1,30 @@
+#%RAML 1.0 Library
+
+usage: |
+  This library contains a set of standard OpenAPI related annotations that are not supported in RAML.
+
+types:
+  externalDocs:
+    properties:
+      description?: string
+      url: string
+
+annotationTypes: 
+  oas-summary: !include oas-summary.raml
+  oas-deprecated: !include oas-deprecated.raml
+  oas-info: !include oas-info.raml
+  oas-tags: !include oas-tags.raml
+  oas-schema-title: !include oas-schema-title.raml
+  oas-schema-exclusiveMaximum: !include oas-schema-exclusiveMaximum.raml
+  oas-schema-exclusiveMinimum: !include oas-schema-exclusiveMinimum.raml
+  oas-schema-format: !include oas-schema-format.raml
+  oas-schema-readOnly: !include oas-schema-readOnly.raml
+  oas-externalDocs: externalDocs
+  oas-tags-definition: !include oas-tags-definition.raml
+  oas-original-definition-name: !include oas-original-schema-name.raml
+  oas-x-: !include oas-extension.raml
+  oas-responses: !include oas-responses.raml
+  oas-responses-default: !include oas-responses-default.raml
+  oas-ref: !include oas-ref.raml
+  oas-parameter-allowEmptyValue: !include oas-parameter-allowEmptyValue.raml
+  oas-parameter-collectionFormat: !include oas-parameter-collectionFormat.raml

annotations/openapi/oas-deprecated.raml

@@ -0,0 +1,10 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `deprecated` property in the OpenAPI Specification that 
+  you are allowed to define for any operation. 
+
+type: boolean
+default: false
+allowedTargets: Method
+displayName: Deprecated (OAS)

annotations/openapi/oas-extension.raml

@@ -0,0 +1,8 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `^x-` property which 
+  is used to define extensions for the OpenAPI Specification. 
+
+type: any
+displayName: Extensions (OAS)

annotations/openapi/oas-info.raml

@@ -0,0 +1,19 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `info` property in the OpenAPI Specification that you 
+  are allowed to define at the root of an OpenAPI document. 
+
+allowedTargets: API
+properties:
+  termsOfService?: string
+  contact?:
+    properties:
+      name?: string
+      url?: string
+      email?: string
+  license?:
+    properties:
+      name?: string
+      url?: string
+displayName: Info (OAS)

annotations/openapi/oas-original-schema-name.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  OpenAPI 2.0 does support the usage of special characters for schema names that RAML
+  does not support for its type system. This annotation stores the original name. 
+
+type: string
+allowedTargets: TypeDeclaration
+displayName: Original Schema Name (OAS)

annotations/openapi/oas-parameter-allowEmptyValue.raml

@@ -0,0 +1,8 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `allowEmptyValue` property in the OpenAPI Specification which 
+  you are allowed to define inside a parameter definition.
+
+type: boolean
+displayName: Parameter AllowEmptyValue (OAS)

annotations/openapi/oas-parameter-collectionFormat.raml

@@ -0,0 +1,10 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `collectionFormat` property in the OpenAPI Specification which 
+  you are allowed to define inside a parameter definition.
+
+type: string 
+enum: [ csv, ssv, tsv, pipes, multi ]
+default: csv
+displayName: Parameter CollectionFormat (OAS)

annotations/openapi/oas-ref.raml

@@ -0,0 +1,10 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `$ref` property in the OpenAPI Specification which 
+  is used to reference to other elements defined in an OpenAPI document. This can be used where `$ref`
+  cannot be directly mapped to something in RAML. For example, you can reference to a response definition
+  under a status code property (e.g. "400").
+
+type: string
+displayName: References (OAS) 

annotations/openapi/oas-responses-default.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `default` property in the OpenAPI Specification which 
+  you are allowed to define as a possible response besides the HTTP status code.
+
+type: any
+allowedTargets: Method
+displayName: Default Responses (OAS)

annotations/openapi/oas-responses.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `responses` property in the OpenAPI Specification which 
+  you are allowed to define at the root of an OpenAPI document.
+
+type: any
+allowedTargets: API
+displayName: Responses (OAS)

annotations/openapi/oas-schema-exclusiveMaximum.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `exclusiveMaximum` property in the OpenAPI Specification which 
+  you are allowed to define inside a schema definition.
+
+type: boolean
+allowedTargets: TypeDeclaration
+displayName: Schema ExclusiveMaximum (OAS)

annotations/openapi/oas-schema-exclusiveMinimum.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `exclusiveMinimum` property in the OpenAPI Specification which 
+  you are allowed to define inside a schema definition.
+
+type: boolean
+allowedTargets: TypeDeclaration
+displayName: Schema ExclusiveMinimum (OAS)

annotations/openapi/oas-schema-format.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `format` property in the OpenAPI Specification which 
+  you are allowed to define inside a schema definition. It should only be used inside "string" types.
+
+type: string
+allowedTargets: TypeDeclaration
+displayName: Schema Format (OAS)

annotations/openapi/oas-schema-readOnly.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `readOnly` property in the OpenAPI Specification which 
+  you are allowed to define inside a schema definition.
+
+type: boolean
+allowedTargets: TypeDeclaration
+displayName: Schema ReadOnly (OAS)

annotations/openapi/oas-schema-title.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `title` property in the OpenAPI Specification which 
+  you are allowed to define for a particular definition. 
+
+type: string
+allowedTargets: TypeDeclaration
+displayName: Schema Title (OAS)

annotations/openapi/oas-summary.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `summary` property in the OpenAPI Specification which 
+  you are allowed to define for any operation. 
+
+type: string
+allowedTargets: Method
+displayName: Summary (OAS)

annotations/openapi/oas-tags-definition.raml

@@ -0,0 +1,16 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `tags` property in the OpenAPI Specification which 
+  you are allowed to define at the root of an OpenAPI document. 
+
+uses:
+  lib: oas-annotations.raml
+
+type: array
+items: 
+  properties: 
+    name: string
+    description?: string
+    externalDocs?: lib.externalDocs
+displayName: Tags Object (OAS) 

annotations/openapi/oas-tags.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 AnnotationTypeDeclaration
+
+usage: |
+  This annotation represents an equivalent to the `tag` property in the OpenAPI Specification which 
+  you are allowed to define for any operation. 
+
+type: string[]
+allowedTargets: Method
+displayName: Tags (OAS)