APIs are everywhere these days, including in packaged applications, cloud services, custom applications, and devices. However, it can be a nightmare for different applications to integrate with each other if everyone used their own standards and mechanisms to define and declare their API interfaces. So, to help with the standardization process and bring some structure to the world of REST APIs, the OpenAPI initiative was created. More details can be found at https://www.openapis.org/.

In order to create APIs that are compliant with OpenAPI Specification (OAS), Swagger (https://swagger.io/) provides various tools that help enable development across the entire API life cycle, from design and documentation to test and deployment.

The AWS API Gateway supports importing or exporting API definitions from the Swagger API format, which is YAML based. To better integrate with the AWS API Gateway, there are additional elements that can be added to the Swagger definition, and the following is a sample YAML for the serverless weather microservice, which has both standard Swagger elements with AWS API Gateway-specific configuration parameters.

In order to use this sample in your environment, please update the region and AWS account number parameters as per your AWS account settings in the following template:

swagger: "2.0"
info:
  title: "Weather Service API"
basePath: "/prod"
schemes:
- "https"
paths:
  /weatherservice:
    get:
      produces:
      - "application/json"
      parameters:
      - name: "appid"
        in: "query"
        required: true
        type: "string"
      - name: "zip"
        in: "query"
        required: true
        type: "string"
      responses:
        200:
          description: "200 response"
          schema:
            $ref: "#/definitions/Empty"
      x-amazon-apigateway-request-validator: "Validate body, query string parameters,
         and headers"
      x-amazon-apigateway-integration:
        responses:
          default:
            statusCode: "200"
        uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:region:account-number:function:${stageVariables.LambdaFunctionName}/invocations
        passthroughBehavior: "when_no_match"
        httpMethod: "POST"
        contentHandling: "CONVERT_TO_TEXT"
        type: "aws_proxy"
    options:
      consumes:
      - "application/json"
      produces:
      - "application/json"
      responses:
        200:
          description: "200 response"
          schema:
            $ref: "#/definitions/Empty"
          headers:
            Access-Control-Allow-Origin:
              type: "string"
            Access-Control-Allow-Methods:
              type: "string"
            Access-Control-Allow-Headers:
              type: "string"
      x-amazon-apigateway-integration:
        responses:
          default:
            statusCode: "200"
            responseParameters:
              method.response.header.Access-Control-Allow-Methods: "'DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT'"
              method.response.header.Access-Control-Allow-Headers: "'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token'"
              method.response.header.Access-Control-Allow-Origin: "'*'"
        requestTemplates:
          application/json: "{"statusCode": 200}"
        passthroughBehavior: "when_no_match"
        type: "mock"
definitions:
  Empty:
    type: "object"
    title: "Empty Schema"
x-amazon-apigateway-request-validators:
  Validate body, query string parameters, and headers:
    validateRequestParameters: true
    validateRequestBody: true