How to use OpenAPI 3.0 with AWS API Gateway to define your APIs

The basic usage of OpenAPI 3.0 in AWS SAM

# sam.yaml
Resources:
  PrivateApi:
    Type: 'AWS::Serverless::Api'
    Properties:
      Name: !Sub ${service}-${branch}-private-api
      StageName: dev
      ...
      DefinitionBody: !Sub |
        openapi: '3.0.0'
        ...
        info:
          title: ${service}
          version: "1.0"
        basePath: "/dev"
        paths:
          /users/{userId}:
            get:
              ...

Add request parameters/body

Request parameters defination

/user
  get:
    description: Query user by user ID
    parameters:
      - in: path
        name: userId
        required: true
        type: string

Request body defination

/user
  post:
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: array
            minItems: 1
            maxItems: 100
            items:
              type: object
              properties:
                userId:
                  type: string
                userName:
                  type: string
                enable:
                  type: boolean
              required:
                - userId
                - userName
                - enable

Enable validation in AWS API Gateway

path:
  ...
x-amazon-apigateway-request-validators:
    all:
      validateRequestParameters: true
      validateRequestBody: true

Resources

https://github.com/awslabs/serverless-application-model/issues/1250
https://docs.aws.amazon.com/lambda/latest/dg/services-apigateway-template.html (Another way to setup api using lambda events.)
https://github.com/awslabs/serverless-application-model/issues/579 (AWS::Serverless::Api - MethodSettings)
https://swagger.io/docs/specification/data-models/data-types/#range
https://swagger.io/docs/specification/describing-request-body/
https://swagger.io/specification/