search

OAI / sig-travel

A repo for managing the travel working group within the OpenAPI Initiative (OAI)
7 stars 1 forks source link

Should DEx use overlays to support local languages #31

Open swaldron58 opened 2 years ago

swaldron58 commented 2 years ago

Can or should the DEx tool adopt the use of overlays to the support of local languages in documentation. I'm leaving the description to that as part of the investigation would be if yes, what is the extent of usage.

slivezey commented 2 years ago

Before getting into the use of overlays, we first need to look at the earlier question of whether the DEx should support compilation of OTM models into RAML libraries. Prior to the RAML 1.0 release, I do not feel that it was mature enough to handle the data structures that could be expressed in the OTM modeling language. As of 1.0, however, new features such as data types and libraries make this much more feasible.

On the topic of RAML overlays (another feature of the 1.0 release), this could be useful for things like multi-language documentation. Overlays could also be severely misused, however, since they do not restrict the types of changes that can be applied to the original API. For this reason, we must be very explicit in how overlays might be employed in OTM-generated API specs.

I feel there are a couple of drawbacks to utilizing overlays for the purpose of providing local language documentation.

  1. OTM models do not currently support multi-language documentation, so an enhancement would be required for both the OTM compiler and OTM DEx tooling. To date, there have been no requests for this capability.
  2. Since other API specification formats such as OpenAPI 2.0 (Swagger) and 3.0 do not support this capability, this would be a RAML-only feature. That is not to say it is impractical or not useful, just that we would have to accept this limitation.
swaldron58 commented 2 years ago

cool. Steve, could you add what kinds of skills and effort we need to update DEx to support RAML? An the additional effort to support overlays? Just ballpark is good enough. I agree overlays could be misused. I mention is as i believe it is a feature of using a tool like DEx. Overlays would just be a means of DEx supporting features such as multi-lingual. It would not be up to an individual developer employ overlays further. it would be up to experts such as yourself on how overlays are to be used, not to an average developer trying to get something out the door in the most expedient way.

slivezey commented 2 years ago

Developer skills would be Java at a senior developer level, including the JavaFX UI framework. Good knowledge of XML and RAML would also be useful.

swaldron58 commented 2 years ago

Links: https://github.com/OAI/Overlay-Specification/discussions