Specify an API

SCRAML uses https://github.com/commercetools/rest-modeling-framework which is based on the RAML API specification

Example API

in api/simple.raml:

copysource#%RAML 1.0
title: Hello world # required title
# taken from https://github.com/raml-org/raml-spec
annotationTypes: !include annotations.raml
# this is not optional, the file included here must follow the format shown 'types.raml'
types: !include types.raml

/greeting: # optional resource
  get: # HTTP method declaration
    queryParameters:
      enum_type:
        type: SomeEnum
      name?:
        type: string
    responses: # declare a response
      200: # HTTP status code
        body: # declare content of response
          application/json: # media type
            type: DataType

Note the use of annotations:

copysource# the package will be used as the file name, currently no actual package structure is generated
package:
  type: string
  allowedTargets: TypeDeclaration
# allows to specify a url for documentation purposes, not reflected in the code currently
docs-uri:
  type: string
# allows to specify all properties will be put into a map
asMap:
  type: object
  properties:
    key: string
    value: string
# allows to override the type used with a full qualified name of a scala type
scala-type:
  type: string
# allows to override the default type for a collection
scala-array-type:
  type: string
# allows to specify an additional supertype like a traited
scala-extends:
  type: string
# allows to control on a granular level if JSON support is enabled for the annotated type
scala-derive-json:
  type: boolean

and types aliases (which will be used for the generated type names):

copysourceBaseType: !include basetype.raml
DataType: !include datatype.raml
DefaultProperty: !include defaultproperty.raml
DerivedWithRequired: !include derivedwithrequired.raml
EmptyBase: !include emptybase.raml
Locale: !include locale.raml
NoProps: !include noprops.raml
ObjectAsMap: !include objectasmap.raml
ObjectAsMapOfArrays: !include objectasmapofarrays.raml
ParentWithOption: !include parentwithoption.raml
SomeEnum: !include enum.raml
EmptySingleton: !include emptysingleton.raml