Use types from one library in another library

[reva2]

Hey guys

I'm a bit new in RAML, so I want ensure that following things supported in RAML 1.0

I'm trying to split my API specification by several files. I have three files:

# ./libraries/jsonapi.raml
#%RAML 1.0 Library

types:
  ResourceRef:
    type: object
    description: Reference to JSON API resource
    properties:
      id:
        type: string
        description: Resource identifier
        required: true
      type:
        type: string
        description: Resource type
        required: true

# ./libraries/sessions.raml
#%RAML 1.0 Library

uses:
  api: jsonapi.raml

types:
  SessionRef:
    type: api.ResourceRef
    description: Reference to resource that represent authentication session
    properties:
      type:
        enum: [sessions]

  Session:
    type: SessionRef
    description: Resource that represent authentication session
    properties:
      attributes:
        type: object
        properties:
          username:
            type: string
            maxLength: 100
            required: false

  SessionsListDoc:
    type: object
    properties:
      data:
        type: Session[]
      include:
        type: array
        items: users.User

#%RAML 1.0
title: My cool API
version: v1
baseUri: http://dev-server.local/api
protocols: [HTTP]

mediaType: application/vnd.api+json

uses:
  sessions: libraries/sessions.raml

/sessions:
  displayName: Sessions
  description: API that allow view and manage authentication sessions
  get:
    description: Returns list of available authentication sessions
    queryParameters:
      include:
        description: |
          Comma-separated list of linked resources that should be
          included into response
        type: string[]
        required: false
    responses:
      200:
        body:
          type: sessions.SessionsListDoc

I want to know is it supported to use one library from another library?

When I try to load this spec to latest version (3.0.6) of API Console it display 'SessionRef' type incorectly. For some reason it doesn't contains 'id' property declared in type 'ResourceRef'.

[sichvoge]

Something is wrong in your library sessions.raml. You are referring to an unknown type users.User.

[n2ygk]

@reva2 Did you ever get to a resolution of this issue? I am also trying to implement a jsonapi.raml library and, when I tried to split off my app's types (which are subclasses of jsonapi:resource and jsonapi:attributes) into a separate file, I get into a namespace issue. This seems to contradict @usarid's statement elsewhere that libraries replace the need for YAML merge (<<) as in this example in which I first have my local definitions inline (which works):

uses: 
  jsonapi: libraries/jsonApiLibrary.raml
types:
  # the sample API's types
  Location:
    type: jsonapi.resource
    description: a warehouse location
    properties:
      attributes:
        type: jsonapi.attributes
        properties:
          warehouse:
            required: true
            type: string
            description: warehouse identifier
          aisle:
            required: true
            type: string
            description: aisle in warehouse
          shelf:
            required: true
            type: string
            description: shelf in aisle
          bin:
            required: true
            type: string
            description: bin on shelf
    additionalProperties: false

and then when trying to externalize these they fail with "inheriting from unknown type" in API Designer:

#%RAML 1.0
# ...
uses: 
  jsonapi: libraries/jsonApiLibrary.raml
types:
  # the sample API's types
  Location: !include libraries/LocationType.raml

#%RAML 1.0 DataType
# Location
uses: 
  jsonapi: libraries/jsonApiLibrary.ram
type: jsonapi.resource
  description: a warehouse location

I'm not sure uses is allowed in a DataType fragment but in any case, it fails to work with or without as jsonapi.resource is not recognized. I've also tried to create a library of my derived types but that also seems to fail due to namespaces.

My goal is to use jsonapi 1.0 for all APIs and to have a reusable type library for my resources where the types are subclasses of jsonapi resources. Am I doing something wrong here?

PS: I see from https://github.com/raml-org/raml-spec/issues/357 that uses is allowed in my DataType fragment, so maybe this is just an API Designer bug?

[n2ygk]

I've played around with this some more and switched everything to a library (no more !includes) and that seems to have resolved it -- in API Designer and the mocking service. Meanwhile Studio 6.3.3/Mule 3.8.3 is throwing errors that indicate it doesn't know how to parse namespaces...

ERROR 2017-09-25 20:50:07,132 [main] org.mule.module.launcher.application.DefaultMuleApplication: null
org.mule.module.apikit.exception.ApikitRuntimeException: Invalid API descriptor -- errors found: 4

Invalid reference 'Widget' -- libraries/collections.raml [line=16, col=37]
Invalid reference 'wid' -- libraries/collections.raml [line=16, col=34]
Invalid reference 'Widget' -- libraries/collections.raml [line=30, col=37]
Invalid reference 'wid' -- libraries/collections.raml [line=30, col=34]

(I had

uses:
   wid: libraries/WidgetTypes.raml

) I upgraded Mule to 3.8.5 and that fixed it. But this is no longer a RAML spec issue so pardon my yammering.