We’re working on an API design project, and have been attempting to wrap our heads fully around RAML 1.0. One of the issues we’ve come across is that we are attempting to separate larger
types into separate files, primarily for readability reasons. A couple of questions:
a) Should we not be doing this? Is the RAML recommendation that all types for example be defined within a single library and/or file?
b) If it’s OK that we want to separate types into separate files, how do we reference a type within a type? IE, let’s say we include a DataType with the following definition:
#%RAML 1.0 DataType type: object parameters: simpleParam: type: typesLibrary.neededType
The only way we have found to do the above would be to create the above not as a DataType but instead as a Library, which then references another library (in the example above,
typesLibrary. This doesn’t seem to make much sense (though, perhaps it is what libraries are intended for) - and we are trying to figure out whether we are approaching this problem wrong by trying to break types into files, or what the best approach is.
As an aside, once we get into DataTypes being libraries, that also seems to introduce the concept of a “complex” data type (IE, one that depends on other data types) vs. a “simple” data type (IE, one that only depends on itself).
I figure that types depending on other types is a common problem (and indeed is referenced in the RC 1.0 docs), so I wanted to find out what we are doing wrong here