Simple RAML 1.0 validator that reads a file containing an API definition and performs a query to each endpoint to check that the RAML matches the backend implementation. It pretends to be a way to prevent the RAML file to be outdated by triggering an error when it doesn't mach with the API. It can be used manually or in a CI environment in order to check the consistency on every build.
Install it globally with:
npm install -g raml-js-validator
If you don't want to install it globally you will need to run it as node_modules/.bin/raml-validate instead of raml-validate
To use it, you can simply run this command:
raml-validate path/to/file.raml
This command will read the RAML definition in the file file.raml and query the backend for each endpoint. If the response codes match the ones specified, no error will be reported. However, if an endpoint fails, an exception will be thrown.
If you want to test the RAML against a different host than the one specified in the RAML file, you can do it this way:
raml-validate path/to/file.raml --target http://localhost:8080
The --target option sets the target server url. If it is not present, it will look for the baseUri attribute in the RAML file. Again, if the RAML doesn't contain any baseUri, the default http://localhost:8080 will be used. Note that you can change the default host defined in the file config.js.
In order to say if a response code is valid or not, raml-validate uses two priorities. By default, if the RAML file contains the response codes, those will be considered the accepted ones and the check will fail if the real response code is not one of those.
However, if the response codes are not present in the API definition, the only accepted code will be the 200 one. Again, you can change the default accepted response codes in the file config.js.
By default, raml-validate doesn't check the response schema. If you want to check it, you can use the option --validate-response. This option will check that the first level of the json keys returned from the API matches the ones defined in the RAML. In the next versions, there will be an option to check all the schema recursively.
Note that to validate the response, you need to have an example response defined in the RAML apart from the type definition. Check the example for more details.
In order to allow raml-validate to check the API with the appropriate uri parameters you should define them with examples:
/task/{taskid}:
uriParameters:
taskid:
type: integer
example: 3
get:
...
If a parameter doesn't have an example, a non deterministic value will be used instead.
Query parameters will be sent to the API if they are defined with an example value:
/url/with/params:
get:
queryParameters:
today:
type: date-only
required: true
example: 2016-11-23
tomorrow:
type: date-only
required: false
example: 2016-11-24
In this case, the tested endpoint would be baseUri/url/with/params?today=2016-11-23&tomorrow=2016-11-24. Note that required field doesn't affect.
In some cases, it is necessary to send data in the body of the request. Specially in POST methods. raml-validate supports it according to the RAML 1.0 syntax:
/task:
post:
description: |
Creates a task
body:
application/x-www-form-urlencoded:
properties:
name:
description: Nam of the task
type: string
example: Code things
owner:
description: Who's going to do it
type: string
example: Joan
In this case, the body of the request would contain the corresponding data in JSON format:
{
name: "Code things",
owner: "Joan"
}
If you browse into the package contents you will find an examples folder. There, you can find an example API and it's own RAML definition. In order check how it works, from a terminal in the directory of the module run:
node examples/server.js
This will start the API. Then from another terminal in the same directory, run:
raml-validate examples/definition.raml
You will see that all the endpoints are correct except from the /unexisting endpoint.
See the CONTRIBUTING.md file.
MIT License (c) 2016 Joan Vilà Cuñat