Serverless OpenAPI Joi Boilerplate Project

Boilerplate serverless API project using serverless-openapi-joi plugin

• Auto-generated OpenAPI v3 docs from code
• Joi validated requests with nice errors
• Swagger UI to view OpenAPI docs, hosted on S3 as a static site (example)
• Example CRUD API
• Local development powered by serverless-offline
• Knex migrations & query builder on PostgreSQL
• Tests with jest
• Travis CI configuration for serverless deployment
• Typescript configuration with sensible defaults
• Prettier + Tslint

Quick Start

Requirements:

• Node.js v8+
• Local PostgreSQL (docker-compose file included)

source .env.sample# Set up environment variables
npm install
docker-compose up --detach # PostgreSQL listening at port 5432
npm run migrate # Set up database schema with knex migrations
npm run dev # Serverless offline: http://localhost:9000, Swagger UI: http://localhost:9001

Codebase

• serverless.yml – serverless config file, defines functions, endpoints and cloudformation resources
• src/** – typescript source files
  • src/handler.ts – serverless main entrypoint, this is where all http requests and function invocations start from
  • src/routes.ts – where api routes and validations are defined
  • src/handler/** – handlers for when routing is finished, this is where control logic happens
  • src/core/** – core business logic + reading & writing to database happens here
  • src/util/** – boring utilities and helpers are stored here
  • src/types/** – type definitions (.d.ts files)
  • src/migrations/** – knex database migration files (use knex migrate:make to create these)
  • src/seeds/** – knex database seed files (use knex seeds:make to create these)
• dist/** – transpiled javascript from source files
• static/** – generated static Swagger UI docs
• scripts/** – reusable scripts like for building static Swagger UI docs
• __tests__/** – jest tests

Deploy

Make sure your AWS IAM access is set-up with sufficient privileges and access keys are set.

export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=

Full deploy with Serverless. (This will take some time on the first time)

npm run build # build project
serverless deploy --stage dev

In order to save time, you can also just deploy a single function and skip Cloudformation after first deploy is finished

serverless deploy function -f <function name> --stage dev