Work with RAML documentation for Serverless v1.0 projects.
Currently it can be used to generate RAML documentation. Future versions will be able to deploy RAML documentents, stub API endpoints based on the RAML and even generate/update serverless.yml files from RAML specifications. For more information, take a look at the Feature Roadmap.
npm install --save raml-serverless
raml-serverless
to your serverless.yml
file (see Serverless docs)Example usage:
sls raml > docs.raml
RAML-Serverless will automatically create a section of the documentation for each HTTP endpoint you have in your serverless.yml
file.
You can put global documentation in the custom:
object in your Yaml file and it will be copied as is into the output RAML. Anything that can go into a RAML file can go here. For example:
custom:
documentation:
raml:
title: My Awesome API
version: v1.0
Which will result in a RAML file that starts with:
#%RAML 1.0
title: My Awsome API
version: v1.0
You can also put RAML on individual HTTP event endpoints and they will be included in the output. For example:
functions:
index:
handler: handlers.index
events:
- http:
path: /hello/world
method: get
cors: true
documentation:
raml:
description: Say hello to the world
Will produce this output in your RAML file:
/hello:
/world:
get:
description: Say hello to the world
You can also include your RAML in a seperate file and import it into your serverless.yml
using variables:
custom:
documentation:
raml: ${file(raml-base.yml)}
This plugin is a work in progress. If you would like to contribute, go to Github issues (/andrewcurioso/raml-serverless/issues) and pick an issue to work on or create a new issue.