simplify-openapi

Simplify Framework - OpenAPI Based Serverless

This REST API model has moved to npm install simplify-openapi -g from version 0.1.9. With new branch of GraphQL Serverless Model at npm install simplify-graphql -g

Initial code based on openapi-codegen

Node.js-based codegen for OpenAPI specs. This project was initially by tailoring from openapi-codegen to use the core code generation functionality to generate the lambda based node projects and AWS CloudFormation stack. There was many tailored code to become a powerful tool nowaday. Thanks to the initial openapi-codegen project that has saved time for developing an initial idea.

Divided code capability:

• Nano function: per individual method (/path/rc: GET) as a lambda function
• Micro function: per some methods (/path/ac: POST, PUT) as a lambda function
• Kilo function: per some resources (/path/rc, /path/ac) as a lambda function
• Mono application: as an application running on a docker-compose service

Deployment mode capability:

• BlueGreen deployment: run latest version as Blue stage or stable version as Green stage
• Enforcement deployment: specify to run a custom enforcement version (e.g maintenance package mode)
• Canary deployment: run one of [latest,stable,enforce] version on-request by x-canary-selection HTTP header

Software development facility:

• Production ready code skeleton (sanitizer, unit tests, api tests, coverage)
• Controllable logging verbosity (INFO, WARN, DEBUG, ERROR) using debug package
• Local and independant development code run (http://localhost:3000) by node express

Install from published NPM packages

• npm install -g simplify-openapi

Install codegen from github sourcode

• git clone https://github.com/simplify-framework/openapi.git
• cd openapi && npm install && npm link

Generate Open API specs sample for pets:

• mkdir pets-project to create project folder for pets
• cd pets-project && npm link simplify-openapi if you install from github
• simplify-openapi template -i petsample to create a petsample OpenAPI 3.0 specs
• simplify-openapi template -i othername to create a othername OpenAPI 3.0 specs

Generate project using command line:

• simplify-openapi -i openapi.yaml to generate code in the current folder
• simplify-openapi -i openapi.yaml -o other-folder to specify another folder

Running with Docker Compose at localhost:

• cd projectPets && docker-compose up -d
• List pets at http://localhost/project-pets/pets
• Feed pets at http://localhost/project-pets/pets/1/feed/2
• docker-compose down to stop running!

Setup AWS configuration profile:

• Create a deployment user in IAM: simplify-user
• Setup IAM Role Policy using: policy-deployment.json
• Setup IAM Role Policy using: policy-services.json
• Setup IAM Role Policy using: policy-execute-api.json
• Configure your machine aws configure --profile simplify-eu (See Pets Project for more information)

Run as AWS Lambda functions:

• npm install to install project dependancies and tools
• npm run stack-deploy to provision code containers (AWS Lambda empty functions)
• npm run push-code to deploy and run code as declared in .env variables (ENV_*)
  • ENV_functionName_DEPLOYMENT_STAGE=(latest|stable|enfoce|canary) to setup running mode
  • ENV_functionName_ENFORCEMENT_PACKAGE=specific-package-name-with-version (enforce mode only)
• npm run stack-destroy to provision code containers (AWS Lambda empty functions)

Serverless architecture in AWS:

• AWS API Gateway REST API
  • AWS Lambda function (service #1)
    • AWS Secret Manager (key vault)
    • Custom resource (external setup)
    • Manage Policy Arn (access policy)
  • AWS Lambda function (service #2)
    • AWS Secret Manager (key vault)
    • Custom resource (external setup)
    • Manage Policy Arn (access policy)
  • AWS Lambda function (service #3)
    • AWS Secret Manager (key vault)
    • Custom resource (external setup)
    • Manage Policy Arn (access policy)

OpenAPI specs with Simplify definitions:

• info.version: define software package version, set for initial packages
• info.title: define software package description, set for initial packages
• x-project-name: to define a project which contains other resources (e.g pets-micro-services)
• x-deployment-name: to define a deployment environment (e.g pets-demo, pets-prod)
• x-deployment-region: to define where to deploy resources (e.g eu-west-1)
• x-deployment-profile: to define a profile that hold the deployment access (e.g simplify-eu)
• x-api-gateway-name: to define an API gateway (Rest API) resource (e.g pets-api-gateway)
• x-api-authorizer-id: provide an authorizer id that linked to API Authorizer (e.g Cognito Auhtorizer)
• x-api-burst-limit: The API request burst limit, the maximum rate limit over a time ranging from one to a few seconds
• x-api-rate-limit: The API request steady-state rate limit.
• x-api-quota-limit: The maximum number of requests that can be made in a given time period.
• x-api-quota-unit: The time period in which the limit applies. Valid values are "DAY", "WEEK" or "MONTH".
  • x-[api/event]-service-runtime: specify service runtime to create function (e.g nodejs12.x, python3.8 )
  • x-[api/event]-service-lang: specific runtime language - is one of javascript or python
  • x-[api/event]-service-name: to define lambda functions that host the source code (e.g pets-service)
  • x-[api/event]-service-model-name: to redirect the related routing paths into a service group (e.g pets)
  • x-[api/event]-service-public: expose or dispose this service path through API gateway (public or not)
  • x-[api/event]-service-authorizer: enable or disable using API Authorizer (e.g using Cognito Authorizer)
  • x-[api/event]-service-api-key: enable to use API Key with x-api-key header to authenticate resource
  • x-[api/event]-service-key-vault: enable or disable key vault service (SecretManager in AWS)
  • x-[api/event]-service-schedule: if set to value (e.g rate(10 minutes)) will schedule every 10 mins
  • x-[api/event]-service-policy: external access policy ARN (e.g Policy ARN to DynamoDB, S3, SNS...)
  • x-[api/event]-service-custom: integrate custom ARN function that trigger for external resource creation/deletion
  • x-[api/event]-service-control: enable or disable service fallen control using hystrix circuit breaker (valid only for docker)
  • x-[api/event]-service-validation: validate request parameters using swagger request validator (parseRequest middleware)
  • x-[api/event]-service-passthrough: passthrough original request from API Gateway to service model for backward compatibility
  • method: define a HTTP Rest API method: (get/put/post/delete)
    • x-control-operation-id or standard operationId: to define a friendly name for this operation method: e.g getPetByName
    • x-control-service-timeout: setup circuit break operation timeout (valid only for docker)
    • x-control-service-duration: setup circuit break operation close duration (valid only for docker)
    • x-control-service-threshold: setup circuit break operation threshold (valid only for docker)

The generated Pets Architecture Diagram