diff --git a/annotations/.gitkeep b/annotations/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/annotations/openapi2.0/README.md b/annotations/openapi2.0/README.md new file mode 100644 index 0000000..f98160b --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-annotations.raml b/annotations/openapi2.0/oas-annotations.raml new file mode 100644 index 0000000..9ec5775 --- /dev/null +++ b/annotations/openapi2.0/oas-annotations.raml @@ -0,0 +1,30 @@ +#%RAML 1.0 Library + +usage: | + This library contains a set of standard OpenAPI 2.0 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 diff --git a/annotations/openapi2.0/oas-deprecated.raml b/annotations/openapi2.0/oas-deprecated.raml new file mode 100644 index 0000000..22c3056 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-extension.raml b/annotations/openapi2.0/oas-extension.raml new file mode 100644 index 0000000..6e91afc --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-info.raml b/annotations/openapi2.0/oas-info.raml new file mode 100644 index 0000000..5da61bf --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-original-schema-name.raml b/annotations/openapi2.0/oas-original-schema-name.raml new file mode 100644 index 0000000..dc36838 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-parameter-allowEmptyValue.raml b/annotations/openapi2.0/oas-parameter-allowEmptyValue.raml new file mode 100644 index 0000000..3253613 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-parameter-collectionFormat.raml b/annotations/openapi2.0/oas-parameter-collectionFormat.raml new file mode 100644 index 0000000..fe924ba --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-ref.raml b/annotations/openapi2.0/oas-ref.raml new file mode 100644 index 0000000..0db8318 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-responses-default.raml b/annotations/openapi2.0/oas-responses-default.raml new file mode 100644 index 0000000..ddf9464 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-responses.raml b/annotations/openapi2.0/oas-responses.raml new file mode 100644 index 0000000..217fbb4 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-schema-exclusiveMaximum.raml b/annotations/openapi2.0/oas-schema-exclusiveMaximum.raml new file mode 100644 index 0000000..ca7fd5a --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-schema-exclusiveMinimum.raml b/annotations/openapi2.0/oas-schema-exclusiveMinimum.raml new file mode 100644 index 0000000..e43b55e --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-schema-format.raml b/annotations/openapi2.0/oas-schema-format.raml new file mode 100644 index 0000000..dc17d6f --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-schema-readOnly.raml b/annotations/openapi2.0/oas-schema-readOnly.raml new file mode 100644 index 0000000..38331ca --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-schema-title.raml b/annotations/openapi2.0/oas-schema-title.raml new file mode 100644 index 0000000..bbd3420 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-summary.raml b/annotations/openapi2.0/oas-summary.raml new file mode 100644 index 0000000..4712b7d --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-tags-definition.raml b/annotations/openapi2.0/oas-tags-definition.raml new file mode 100644 index 0000000..7c0848a --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file diff --git a/annotations/openapi2.0/oas-tags.raml b/annotations/openapi2.0/oas-tags.raml new file mode 100644 index 0000000..7307e17 --- /dev/null +++ b/annotations/openapi2.0/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) \ No newline at end of file