Support tags in OpenAPI Object

[kylef]

This likely requires design in API Elements specification and designing how to expose this information in API Elements.

[galcohen92]

I would like to work on this issue, but I need more info about api-elements's structure, where is each field mapped to? I found this docs but it only explain the general structure not a specific mappings, for example where its written that info.title mapped to parseResult.api.title?

[kylef]

Hi @galcohen92, this field cannot currently be mapped to API Elements, the intermediate form of API Description formats and Apiary. The first step in this task is proposing a concept of tagging, or classifications to API Elements. Once that design is agreed upon then it would be a matter of updating API Elements specification (releasing API Elements 1.1 or such with all other changes needed for other OAS 3 features), this must not be a breaking change. We would then need to implement the functionality in the OAS 3 (and OAS 2) parser. Then tools such as Apiary Documentation, Dredd etc would need to be updated to make use of these classifiers.

As this adapter is still in early stages, our first focus is to implement all of the functionality from OpenAPI 3 that we can already describe in the current version of API Elements 1.0 for version 1 of our adapter. Once that is done we would then go over unsupported functionality and introduce these concepts into API Elements and our subseqent tooling.

---

• [ ] Design how we can represent a classifications (or tags) system in API Elements. I think we should think about the concept and figure out how it can best fit into API Elements. We should do research into how other API Descriptions make use of classifications. We want to avoid designing API Element features specifically around a single API Description format and instead a design a cannonical format that fits.
• [ ] Update API Elements Specification
• [ ] Implement in OAS 3 Parser (and minim-api-description)
• [ ] Implement in OAS 2 Parser
• [ ] Schedule implementations in other products making use of API Elements
  • [ ] Dredd
  • [ ] ApiaryUI (Documentation)
  • [ ] Apiary Styleguides / Constitutions

[fscorro]

Hi @kylef, is there any update about this issue?

[tylermilner]

I'll be following this. I created an API in Postman using openapi 3.0 format and, following the auto-generated sample spec, added tags properties to my requests. I got tired of writing the spec inside of Postman so I copy/pasted it to Apiary and a bunch of 'Operation Object' contains unsupported key 'tags' semantic issues popped up. I guess Apiary doesn't fully support the openapi 3.0 spec? I see information about using tags in the Swagger openapi documentation.

[KlausGrosser]

Any progress? With all of these unsupported stuff it is almost impossible to parse successfully