From 1b36b19b573a7aad78f3b1a79dc2a3898875b52e Mon Sep 17 00:00:00 2001 From: sichvoge Date: Fri, 23 Jun 2017 12:14:13 +0100 Subject: [PATCH 1/2] added openapi 2.0 annotations --- annotations/.gitkeep | 0 annotations/openapi/README.md | 9 ++++++ annotations/openapi/oas-annotations.raml | 30 +++++++++++++++++++ annotations/openapi/oas-deprecated.raml | 10 +++++++ annotations/openapi/oas-extension.raml | 8 +++++ annotations/openapi/oas-info.raml | 19 ++++++++++++ .../openapi/oas-original-schema-name.raml | 9 ++++++ .../oas-parameter-allowEmptyValue.raml | 8 +++++ .../oas-parameter-collectionFormat.raml | 10 +++++++ annotations/openapi/oas-ref.raml | 10 +++++++ .../openapi/oas-responses-default.raml | 9 ++++++ annotations/openapi/oas-responses.raml | 9 ++++++ .../openapi/oas-schema-exclusiveMaximum.raml | 9 ++++++ .../openapi/oas-schema-exclusiveMinimum.raml | 9 ++++++ annotations/openapi/oas-schema-format.raml | 9 ++++++ annotations/openapi/oas-schema-readOnly.raml | 9 ++++++ annotations/openapi/oas-schema-title.raml | 9 ++++++ annotations/openapi/oas-summary.raml | 9 ++++++ annotations/openapi/oas-tags-definition.raml | 16 ++++++++++ annotations/openapi/oas-tags.raml | 9 ++++++ 20 files changed, 210 insertions(+) delete mode 100644 annotations/.gitkeep create mode 100644 annotations/openapi/README.md create mode 100644 annotations/openapi/oas-annotations.raml create mode 100644 annotations/openapi/oas-deprecated.raml create mode 100644 annotations/openapi/oas-extension.raml create mode 100644 annotations/openapi/oas-info.raml create mode 100644 annotations/openapi/oas-original-schema-name.raml create mode 100644 annotations/openapi/oas-parameter-allowEmptyValue.raml create mode 100644 annotations/openapi/oas-parameter-collectionFormat.raml create mode 100644 annotations/openapi/oas-ref.raml create mode 100644 annotations/openapi/oas-responses-default.raml create mode 100644 annotations/openapi/oas-responses.raml create mode 100644 annotations/openapi/oas-schema-exclusiveMaximum.raml create mode 100644 annotations/openapi/oas-schema-exclusiveMinimum.raml create mode 100644 annotations/openapi/oas-schema-format.raml create mode 100644 annotations/openapi/oas-schema-readOnly.raml create mode 100644 annotations/openapi/oas-schema-title.raml create mode 100644 annotations/openapi/oas-summary.raml create mode 100644 annotations/openapi/oas-tags-definition.raml create mode 100644 annotations/openapi/oas-tags.raml diff --git a/annotations/.gitkeep b/annotations/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/annotations/openapi/README.md b/annotations/openapi/README.md new file mode 100644 index 0000000..f98160b --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-annotations.raml b/annotations/openapi/oas-annotations.raml new file mode 100644 index 0000000..07f6946 --- /dev/null +++ b/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 diff --git a/annotations/openapi/oas-deprecated.raml b/annotations/openapi/oas-deprecated.raml new file mode 100644 index 0000000..22c3056 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-extension.raml b/annotations/openapi/oas-extension.raml new file mode 100644 index 0000000..6e91afc --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-info.raml b/annotations/openapi/oas-info.raml new file mode 100644 index 0000000..5da61bf --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-original-schema-name.raml b/annotations/openapi/oas-original-schema-name.raml new file mode 100644 index 0000000..dc36838 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-parameter-allowEmptyValue.raml b/annotations/openapi/oas-parameter-allowEmptyValue.raml new file mode 100644 index 0000000..3253613 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-parameter-collectionFormat.raml b/annotations/openapi/oas-parameter-collectionFormat.raml new file mode 100644 index 0000000..fe924ba --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-ref.raml b/annotations/openapi/oas-ref.raml new file mode 100644 index 0000000..0db8318 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-responses-default.raml b/annotations/openapi/oas-responses-default.raml new file mode 100644 index 0000000..ddf9464 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-responses.raml b/annotations/openapi/oas-responses.raml new file mode 100644 index 0000000..217fbb4 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-schema-exclusiveMaximum.raml b/annotations/openapi/oas-schema-exclusiveMaximum.raml new file mode 100644 index 0000000..ca7fd5a --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-schema-exclusiveMinimum.raml b/annotations/openapi/oas-schema-exclusiveMinimum.raml new file mode 100644 index 0000000..e43b55e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-schema-format.raml b/annotations/openapi/oas-schema-format.raml new file mode 100644 index 0000000..dc17d6f --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-schema-readOnly.raml b/annotations/openapi/oas-schema-readOnly.raml new file mode 100644 index 0000000..38331ca --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-schema-title.raml b/annotations/openapi/oas-schema-title.raml new file mode 100644 index 0000000..bbd3420 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-summary.raml b/annotations/openapi/oas-summary.raml new file mode 100644 index 0000000..4712b7d --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-tags-definition.raml b/annotations/openapi/oas-tags-definition.raml new file mode 100644 index 0000000..7c0848a --- /dev/null +++ b/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) \ No newline at end of file diff --git a/annotations/openapi/oas-tags.raml b/annotations/openapi/oas-tags.raml new file mode 100644 index 0000000..7307e17 --- /dev/null +++ b/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) \ No newline at end of file From 7ae9019060a41566e76f7dd9599669895fa4f1ea Mon Sep 17 00:00:00 2001 From: sichvoge Date: Fri, 23 Jun 2017 12:15:09 +0100 Subject: [PATCH 2/2] renamed folder to reflect version of openapi --- annotations/{openapi => openapi2.0}/README.md | 0 annotations/{openapi => openapi2.0}/oas-annotations.raml | 2 +- annotations/{openapi => openapi2.0}/oas-deprecated.raml | 0 annotations/{openapi => openapi2.0}/oas-extension.raml | 0 annotations/{openapi => openapi2.0}/oas-info.raml | 0 .../{openapi => openapi2.0}/oas-original-schema-name.raml | 0 .../{openapi => openapi2.0}/oas-parameter-allowEmptyValue.raml | 0 .../{openapi => openapi2.0}/oas-parameter-collectionFormat.raml | 0 annotations/{openapi => openapi2.0}/oas-ref.raml | 0 annotations/{openapi => openapi2.0}/oas-responses-default.raml | 0 annotations/{openapi => openapi2.0}/oas-responses.raml | 0 .../{openapi => openapi2.0}/oas-schema-exclusiveMaximum.raml | 0 .../{openapi => openapi2.0}/oas-schema-exclusiveMinimum.raml | 0 annotations/{openapi => openapi2.0}/oas-schema-format.raml | 0 annotations/{openapi => openapi2.0}/oas-schema-readOnly.raml | 0 annotations/{openapi => openapi2.0}/oas-schema-title.raml | 0 annotations/{openapi => openapi2.0}/oas-summary.raml | 0 annotations/{openapi => openapi2.0}/oas-tags-definition.raml | 0 annotations/{openapi => openapi2.0}/oas-tags.raml | 0 19 files changed, 1 insertion(+), 1 deletion(-) rename annotations/{openapi => openapi2.0}/README.md (100%) rename annotations/{openapi => openapi2.0}/oas-annotations.raml (91%) rename annotations/{openapi => openapi2.0}/oas-deprecated.raml (100%) rename annotations/{openapi => openapi2.0}/oas-extension.raml (100%) rename annotations/{openapi => openapi2.0}/oas-info.raml (100%) rename annotations/{openapi => openapi2.0}/oas-original-schema-name.raml (100%) rename annotations/{openapi => openapi2.0}/oas-parameter-allowEmptyValue.raml (100%) rename annotations/{openapi => openapi2.0}/oas-parameter-collectionFormat.raml (100%) rename annotations/{openapi => openapi2.0}/oas-ref.raml (100%) rename annotations/{openapi => openapi2.0}/oas-responses-default.raml (100%) rename annotations/{openapi => openapi2.0}/oas-responses.raml (100%) rename annotations/{openapi => openapi2.0}/oas-schema-exclusiveMaximum.raml (100%) rename annotations/{openapi => openapi2.0}/oas-schema-exclusiveMinimum.raml (100%) rename annotations/{openapi => openapi2.0}/oas-schema-format.raml (100%) rename annotations/{openapi => openapi2.0}/oas-schema-readOnly.raml (100%) rename annotations/{openapi => openapi2.0}/oas-schema-title.raml (100%) rename annotations/{openapi => openapi2.0}/oas-summary.raml (100%) rename annotations/{openapi => openapi2.0}/oas-tags-definition.raml (100%) rename annotations/{openapi => openapi2.0}/oas-tags.raml (100%) diff --git a/annotations/openapi/README.md b/annotations/openapi2.0/README.md similarity index 100% rename from annotations/openapi/README.md rename to annotations/openapi2.0/README.md diff --git a/annotations/openapi/oas-annotations.raml b/annotations/openapi2.0/oas-annotations.raml similarity index 91% rename from annotations/openapi/oas-annotations.raml rename to annotations/openapi2.0/oas-annotations.raml index 07f6946..9ec5775 100644 --- a/annotations/openapi/oas-annotations.raml +++ b/annotations/openapi2.0/oas-annotations.raml @@ -1,7 +1,7 @@ #%RAML 1.0 Library usage: | - This library contains a set of standard OpenAPI related annotations that are not supported in RAML. + This library contains a set of standard OpenAPI 2.0 related annotations that are not supported in RAML. types: externalDocs: diff --git a/annotations/openapi/oas-deprecated.raml b/annotations/openapi2.0/oas-deprecated.raml similarity index 100% rename from annotations/openapi/oas-deprecated.raml rename to annotations/openapi2.0/oas-deprecated.raml diff --git a/annotations/openapi/oas-extension.raml b/annotations/openapi2.0/oas-extension.raml similarity index 100% rename from annotations/openapi/oas-extension.raml rename to annotations/openapi2.0/oas-extension.raml diff --git a/annotations/openapi/oas-info.raml b/annotations/openapi2.0/oas-info.raml similarity index 100% rename from annotations/openapi/oas-info.raml rename to annotations/openapi2.0/oas-info.raml diff --git a/annotations/openapi/oas-original-schema-name.raml b/annotations/openapi2.0/oas-original-schema-name.raml similarity index 100% rename from annotations/openapi/oas-original-schema-name.raml rename to annotations/openapi2.0/oas-original-schema-name.raml diff --git a/annotations/openapi/oas-parameter-allowEmptyValue.raml b/annotations/openapi2.0/oas-parameter-allowEmptyValue.raml similarity index 100% rename from annotations/openapi/oas-parameter-allowEmptyValue.raml rename to annotations/openapi2.0/oas-parameter-allowEmptyValue.raml diff --git a/annotations/openapi/oas-parameter-collectionFormat.raml b/annotations/openapi2.0/oas-parameter-collectionFormat.raml similarity index 100% rename from annotations/openapi/oas-parameter-collectionFormat.raml rename to annotations/openapi2.0/oas-parameter-collectionFormat.raml diff --git a/annotations/openapi/oas-ref.raml b/annotations/openapi2.0/oas-ref.raml similarity index 100% rename from annotations/openapi/oas-ref.raml rename to annotations/openapi2.0/oas-ref.raml diff --git a/annotations/openapi/oas-responses-default.raml b/annotations/openapi2.0/oas-responses-default.raml similarity index 100% rename from annotations/openapi/oas-responses-default.raml rename to annotations/openapi2.0/oas-responses-default.raml diff --git a/annotations/openapi/oas-responses.raml b/annotations/openapi2.0/oas-responses.raml similarity index 100% rename from annotations/openapi/oas-responses.raml rename to annotations/openapi2.0/oas-responses.raml diff --git a/annotations/openapi/oas-schema-exclusiveMaximum.raml b/annotations/openapi2.0/oas-schema-exclusiveMaximum.raml similarity index 100% rename from annotations/openapi/oas-schema-exclusiveMaximum.raml rename to annotations/openapi2.0/oas-schema-exclusiveMaximum.raml diff --git a/annotations/openapi/oas-schema-exclusiveMinimum.raml b/annotations/openapi2.0/oas-schema-exclusiveMinimum.raml similarity index 100% rename from annotations/openapi/oas-schema-exclusiveMinimum.raml rename to annotations/openapi2.0/oas-schema-exclusiveMinimum.raml diff --git a/annotations/openapi/oas-schema-format.raml b/annotations/openapi2.0/oas-schema-format.raml similarity index 100% rename from annotations/openapi/oas-schema-format.raml rename to annotations/openapi2.0/oas-schema-format.raml diff --git a/annotations/openapi/oas-schema-readOnly.raml b/annotations/openapi2.0/oas-schema-readOnly.raml similarity index 100% rename from annotations/openapi/oas-schema-readOnly.raml rename to annotations/openapi2.0/oas-schema-readOnly.raml diff --git a/annotations/openapi/oas-schema-title.raml b/annotations/openapi2.0/oas-schema-title.raml similarity index 100% rename from annotations/openapi/oas-schema-title.raml rename to annotations/openapi2.0/oas-schema-title.raml diff --git a/annotations/openapi/oas-summary.raml b/annotations/openapi2.0/oas-summary.raml similarity index 100% rename from annotations/openapi/oas-summary.raml rename to annotations/openapi2.0/oas-summary.raml diff --git a/annotations/openapi/oas-tags-definition.raml b/annotations/openapi2.0/oas-tags-definition.raml similarity index 100% rename from annotations/openapi/oas-tags-definition.raml rename to annotations/openapi2.0/oas-tags-definition.raml diff --git a/annotations/openapi/oas-tags.raml b/annotations/openapi2.0/oas-tags.raml similarity index 100% rename from annotations/openapi/oas-tags.raml rename to annotations/openapi2.0/oas-tags.raml