search

RepreZen / Semoasa

Specification Extension Metadata for OAS Annotations (Semoasa) is a machine-readable format for extensions to Swagger/OpenAPI 2.0 and 3.0 specifications.
29 stars 1 forks source link

Round-tripping to RAML 1.0 annotations #7

Open MikeRalphson opened 6 years ago

MikeRalphson commented 6 years ago

From a brief reading of the relevant part of the spec all we may be missing is an optional displayName.

A friendly name used only for display or documentation purposes. The default is the element key, the name of the annotation itself.

As this seems distinct from the summary, and description maps 1:1.

A raml1 - RAML1 Context Object may not be necessary if the allowedTargets can be deduced from whichever oas2 or oas3 one is converting from.

tedepstein commented 6 years ago

@MikeRalphson , I like the idea of supporting usage contexts other than OAS. But in that case, I'm not sure if there's any reason to resist adding a raml1 context object for that purpose. That would seem to be the most natural way to do it, and the most natural home for a displayName property.

We could also add an enum for allowedTargets, aligned with RAML, so we don't need any translation or interpretation between OAS and RAML.

And we could add a name or ramlName property, to allow more idiomatic naming of annotations in the RAML context. AFAIK, the x- prefix is really an OAS-specific requirement.

MikeRalphson commented 6 years ago

@tedepstein That does sound cleaner, I just wasn't sure if you wanted to keep SEMOASA as 'pure' OAS-centric.