Added annotations to reflect OpenAPI 2.0 properties #2
Conversation
There was a problem hiding this comment.
Hi @sichvoge as for me some annotations proposed here have more generic meaning so it would be better to declare them as a generic annotations,
for example tags instead of oas-tags.
Also I see potential problem with oas-parameter-collection-format and oas-x- annotations.
Regards,
Pavel
|
|
||
| annotationTypes: | ||
| oas-summary: !include oas-summary.raml | ||
| oas-deprecated: !include oas-deprecated.raml |
There was a problem hiding this comment.
As for me it is more logical to create generic deprecated annotation, which is not specific to oas.
| oas-summary: !include oas-summary.raml | ||
| oas-deprecated: !include oas-deprecated.raml | ||
| oas-info: !include oas-info.raml | ||
| oas-tags: !include oas-tags.raml |
There was a problem hiding this comment.
tags - also looks as a pretty generic thing.
|
|
||
| type: boolean | ||
| default: false | ||
| allowedTargets: Method |
There was a problem hiding this comment.
why we should constrain it to Methods only.
| is used to define extensions for the OpenAPI Specification. | ||
|
|
||
| type: any | ||
| displayName: Extensions (OAS) |
There was a problem hiding this comment.
As for me it does not looks like a good idea to convert all extensions into 1 annotation. (Imagine round trip from RAML to OAS and back, ideally we should convert raml annotations to extensions and then back to same annotations)
| @@ -0,0 +1,10 @@ | |||
| #%RAML 1.0 AnnotationTypeDeclaration | |||
There was a problem hiding this comment.
It seems that we have a hidden problem with this annotation. (In RAML we have a strict definition of how arrays of the scalars should be serialised and it seems that it depends from position where we are referencing array type) :-(
| 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 |
There was a problem hiding this comment.
oas-responses-default this one also looks pretty generic.
| you are allowed to define inside a parameter definition. | ||
|
|
||
| type: boolean | ||
| displayName: Parameter AllowEmptyValue (OAS) |
There was a problem hiding this comment.
I guess we should add allowedTargets: TypeDeclaration facet to this
annotations/openapi/oas-tags.raml
Outdated
| you are allowed to define for any operation. | ||
|
|
||
| type: string[] | ||
| allowedTargets: Method |
There was a problem hiding this comment.
Why it is only allowed to tag methods?
|
Hi, Pavel. Thanks for your comments. I agree to the more generic What potential problems do you see with |
that's true, but on other side, let's say that we have a console which would like to group resources by
The one with
No let's imagine that we have raml->oas->raml conversion chain. I would expect that if my original RAML file has 3 annotations with a names |
This PR adds standard annotations that reflect OpenAPI 2.0 properties missing in RAML 1.0.