Awesome
serverless-models-plugin
This plugin adds the missing model support to Serverless 0.5.x.
Overview
The plugin lets you define your models within your project. Models are important as soon as you play around with the mobile SDK's generated by AWS Gateway. They define the typed results or inputs of your API definition and are mapped to classes in the SDK's. One advantage is, that if a model is used in more than one endpoints of your API, or a model references other models for its sub-objects, the generated SDK uses exactly the same class definition instance throughout the SDK.
As soon as you reference them within your endpoint definitions and deploy the endpiont, the needed models are uploaded to API Gateway. If the model already exists, the definition is updated.
Installation
-
Install the plugin module
npm install serverless-models-plugin
will install the latest version of the plugin.If you want to debug, you also can reference the source repository at a specific version or branch with
npm install https://github.com/HyperBrain/serverless-models-plugin#<tag or branch name>
-
Activate the plugin in your Serverless project Add
serverless-models-plugin
to the plugins array in yours-project.json
.{ "name": "testp1", "custom": {}, "plugins": [ "serverless-models-plugin" ] }
Usage
Model definition
Within anywhere of your Serverless project space you can create a s-models.json
or s-models.yaml
(both formats are
supported). Within this files define your models ( you can $ref models between s-models files).
functions/
└── function1
├── event.json
├── handler.js
├── s-function.json
└── s-models.json
Example (YAML)
myModelOne:
'$schema': 'http://json-schema.org/draft-04/schema#'
type: object
properties:
myProp:
type: string
myProp2:
type: number
myModelTwo:
'$schema': 'http://json-schema.org/draft-04/schema#'
type: array
items:
type: string
Example (JSON)
{
"myModelOne": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"myProp": {
"type": "string"
},
"myProp2": {
"type": "number"
}
}
},
"myModelTwo": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"items": {
"type": "string"
}
}
}
Model references
Models can reference other models. You can do this easily by adding $ref
properties that
refer to another defined model. The plugin will take care of including and deploying referenced
models properly.
Example (YAML)
myModelOne:
'$schema': 'http://json-schema.org/draft-04/schema#'
type: object
properties:
myProp:
type: string
myProp2:
type: number
myModelTwo:
'$schema': 'http://json-schema.org/draft-04/schema#'
type: array
items:
$ref: myModelOne
Example (JSON)
{
"myModelOne": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"myProp": {
"type": "string"
},
"myProp2": {
"type": "number"
}
}
},
"myModelTwo": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"items": {
"$ref": "myModelOne"
}
}
}
Using models in endpoints
If you want to declare a response (output) or request (input) model for an endpoint, you just have
to add it to your s-function.json
accordingly (see requestModels and responseModels properties):
{
"name": "testfct2",
"runtime": "nodejs",
"description": "Serverless Lambda function for project: testp1",
"customName": false,
"customRole": false,
"handler": "handler.handler",
"timeout": 6,
"memorySize": 1024,
"authorizer": {},
"custom": {
"excludePatterns": []
},
"endpoints": [
{
"path": "testfct2",
"method": "GET",
"type": "AWS",
"authorizationType": "none",
"authorizerFunction": false,
"apiKeyRequired": false,
"requestParameters": {},
"requestModels": {
"application/json": "myModelOne"
},
"requestTemplates": {
"application/json": ""
},
"responses": {
"400": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {},
"responseModels": {
"application/json": "myModelTwo"
},
"responseTemplates": {
"application/json": ""
}
}
}
}
],
"events": [],
"environment": {
"SERVERLESS_PROJECT": "${project}",
"SERVERLESS_STAGE": "${stage}",
"SERVERLESS_REGION": "${region}"
},
"vpc": {
"securityGroupIds": [],
"subnetIds": []
}
}
Helper commands
The plugin also adds some new commands to Serverless: sls models XXXXXX
list
Lists the defined model names
show
Shows specified model definitions as JSON or YAML.
Usage: sls models show <model names> [--format json|yaml]
more to come
Releases
1.1.0
- s-models.[yaml|json] files are now used throughout the project hierarchy and merged on deploy.
1.0.0
- Initial release
1.0.1
- Documentation enhancements: issues #1, #2
1.1.0
- Documentation enhancements: issues #9
- Added support for placing s-models within anywhere of the project's space