Usage¶
You can use ramlfications
to parse and validate a RAML file with Python.
With the command line, you can validate or visualize the RAML-defined API as a tree.
Parse¶
To parse a RAML file, include ramlfications in your project and call the parse function:
>>> import ramlfications
>>> RAML_FILE = "/path/to/my-api.raml"
>>> api = ramlfications.parse(RAML_FILE)
>>> api
<RootNode(raml_file="path/to/my-api.raml")>
>>> api.title
'My Foo API'
>>> api.version
'v1'
>>> api.security_schemes
[<SecurityScheme(name="oauth_2_0")>]
>>> oauth2 = api.security_schemes[0]
>>> oauth2.name
'oauth_2_0'
>>> oauth2.type
'OAuth 2.0'
>>> oauth2.settings.scopes
['playlist-read-private', 'playlist-modify-public',..., 'user-read-email']
>>> oauth2.settings.access_token_uri
'https://accounts.foo.com/api/token'
>>> api.resources
[<ResourceNode(method='GET', path='/foo')>, <ResourceNode(method='PUT', path='/foo')>, ..., <ResourceNode(method='GET', path='/foo/bar/{id}')>]
>>> foo_bar = api.resources[-1]
>>> foo_bar.name
'/{id}'
>>> foo_bar.display_name
'fooBarID'
>>> foo_bar.absolute_path
'https://api.foo.com/v1/foo/bar/{id}'
>>> foo_bar.uri_params
[<URIParameter(name='id')>]
>>> uri_param = foo_bar.uri_params[0]
>>> uri_param.required
True
>>> uri_param.type
'string'
>>> id_param.example
'f00b@r1D'
You can pass in an optional config file to add additional values for certain parameters. Find out more within the Extended Usage:
>>> CONFIG_FILE = "/path/to/config.ini"
>>> api = ramlfications.parse(RAML_FILE, CONFIG_FILE)
For more complete understanding of what’s available when parsing a RAML file, check the Extended Usage or the API Definition.
Validate¶
Validation is according to the RAML Specification.
To validate a RAML file via the command line:
$ ramlfications validate /path/to/my-api.raml
Success! Valid RAML file: tests/data/examples/simple-tree.raml
$ ramlfications validate /path/to/invalid/no-title.raml
Error validating file /path/to/invalid/no-title.raml: RAML File does not define an API title.
To validate a RAML file with Python:
>>> from ramlfications import validate
>>> RAML_FILE = "/path/to/my-api.raml"
>>> validate(RAML_FILE)
>>>
>>> from ramlfications import validate
>>> RAML_FILE = "/path/to/invalid/no-title.raml"
>>> validate(RAML_FILE)
InvalidRootNodeError: RAML File does not define an API title.
Note
When using validate
within Python (versus the command line utility), if the RAML file is valid, then nothing is returned. Only invalid files will return an exception.
Tree¶
To visualize a tree output of a RAML file:
$ ramlfications tree /path/to/my-api.raml [-c|--color light/dark] [-v|vv|vvv] [-o|--output]
The least verbose option would show something like this:
$ ramlfications tree /path/to/my-api.raml
==========
My Foo API
==========
Base URI: https://api.foo.com/v1
|– /foo
| – /bar
| – /bar/{id}
And the most verbose:
$ ramlfications tree /path/to/my-api.raml -vvv
==========
My Foo API
==========
Base URI: https://api.foo.com/v1
|– /foo
| ⌙ GET
| Query Params
| ⌙ q: Foo Query
| ⌙ type: Item Type
| – /bar
| ⌙ GET
| Query Params
| ⌙ q: Bar Query
| ⌙ type: item type
| – /bar/{id}
| ⌙ GET
| URI Params
| ⌙ id: ID of foo
Options and Arguments¶
The full usage is:
$ ramlfications [OPTIONS] COMMAND RAMLFILE
The RAMLFILE
is a file containing the RAML-defined API you’d like to work with.
Valid COMMAND
s are the following:
-
validate
¶
Validate the RAML file according to the RAML Specification.
-
tree
¶
Visualize the RAML file via your console.
Valid OPTIONS
for all commands are the following:
-
--help
¶
Show a brief usage summary and exit.
Valid OPTIONS
for the tree
command are the following:
-
-c
light|dark
¶ Use a light color scheme for dark terminal backgrounds [DEFAULT], or dark color scheme for light backgrounds.
-
--color
light|dark
¶ Use a light color scheme for dark terminal backgrounds [DEFAULT], or dark color scheme for light backgrounds.
-
-o
¶
Save tree output desired file
-
--output
¶
Save tree output desired file
-
-v
¶
Increase verbose output of the tree one level: adds the HTTP methods
-
-vv
¶
Increase verbose output of the tree one level: adds the parameter names
-
-vvv
¶
Increase verbose output of the tree one level: adds the parameter display name