RAML v1.0: Named Examples - jdiegodcp/ramlfications GitHub Wiki
Examples
Related issues:
Examples as described in the RAML spec
- Sort of separate from
example
attribute that already exists; this new feature is sometimes referred to as "Named Examples" - Applies only to Data Types and Named Parameters
examples
property may be used to attach multiple examplesexamples
can be a map/dictionary
Broad Implementation TODOs
- Parse similar to data types, resource types, etc with own object
- Able to handle both arrays and maps/dicts for
examples
example
as defined in a Data Type will mirror the same properties as the Data Type's properties, e.g. a map of key/value pairs- If
strict
is set to false, then validation of the primative type of the example shouldn't happen
Validation
- Each example has the following properties; all are optional except for
content
:displayName
description
(<annotationName>)
content
strict
Where to start
- A new
Example
object should probably be defined inramlfications/raml.py
- When parsing DataTypes, the
example
and/orexamples
property should be appropriately parsed, and validated (e.g. the type of example matches the expected type defined in the property itself) - In
ramlfications/parser.py
, there should be a function within the data type function to create these example objects ramlfications/validate.py
should ensure the above validation- This should probably be tackled at the same time Data Types are tackled.
Proposed API behavior
Input
Main RAML file, api.raml
:
#%RAML 1.0
title: API with Examples
types:
User:
type: object
properties:
name: string
lastname: string
example:
name: Bob
lastname: Marley
Org:
type: object
properties:
name: string
address?: string
examples:
acme:
content:
name: Acme
softwareCorp:
content:
name: Software Corp
address: 35 Central Street
Expected output
>>> RAML_FILE = "api.raml"
>>> api = ramlfications.parse(RAML_FILE, version="1.0")
>>> api.title
'API with Examples'
>>> user = api.data_types[0]
>>> user
DataType(name='User')
>>> user.examples # not set so nothing returns
>>> user.example
Example(of='User')
>>> dir(user.example) # skipping dunders
['name',
'lastname',
'type']
>>> user.example.name
'Bob'
>>> user.example.lastname
'Marley'
>>> user.example.type
str # or 'string'
>>> org = api.data_types[1]
>>> org.example # not set so nothing returns
>>> org.examples
[Example(of='Org'), Example(of='Org')] # not sure how to diff these two
>>> org.examples[0].name
'Acme'
>>> org.examples[1].name
'Software Corp'
>>> org.examples[1].address
'35 Central Street'