commercetools
Using types across different api-spec RAMLs and doc generation
We sometimes need to refer to types across microsites in documentation. However, the auto-generated links to data types are designed to work only within a microsite. In the future, API docs may be written across many microsite but source from one RAML spec.
Not in scope here: Autolinking to handwritten or external types ( #864 (
We talked about this issue in our daily on December 17, 2020. See Agenda in this note.
@jenschude FYI here's a topic that was obvious to pop up at some point.
A completely monolithic model has already turned out to no be ideal and hard to maintain, but I can imagine other ways to achieve the global type namespace and the consistency checks here.
- allowing duplicates but having test runs on CI that verify that if two types across all RAML models have the same name they need to be exactly the same, too (at least modeled the same, description text deviations may be intentional and helpful).
- using RAML libraries, but without the namespacing (like import API does).
When starting to write the api reference I used libraries. But the issue was that the tooling was getting slower and slower by using them.
And libraries are only be able to be impoted namespaced. Even worse at the point where they are used.
And import api uses namespaces but the codegen removes them as they have no value in the sdk itself
Thanks @jenschude - I forgot that libraries wouldn't even cover the namespacing issue anyways (which is an ugly one because it pops up in graphQL anyways). So we'd have to run with some sort of custom separate validation or consistency test anyways, right?
PS: and/or do it the dirty way and include the same type declaration in multiple APIs without using the RAML library feature.
That would be the pattern we thought about anyways when we want to provide "partial" API declarations.
I would go the "package" way and say each api defines its type in a package. So either we add in the docs kit the option to split the types by its belonging api or i can prefix them or add meta data using annotations in the code gen
We need to put this on hold until the future structure of the documentation website is defined. Currently two approaches are discussed - one has all the APIs in one microsite (would mean we don't need this here any more), the other intends to split the complete content (including tutorials, introduction, API, graphQL etc) into "domain" microsites like cart & order. The latter would make this very important and critical.
Please remove the "blocked" label once decided.