serverless.yml

service: serverless-openapi-doc-demo

frameworkVersion: '2'
provider:
  name: aws
  runtime: nodejs14.10

functions:
  createUser:
    handler: handler.create
    events:
      - httpApi:
          path: create
          method: post
          authorizer:
            name: customAuth
          documentation:
            summary: Create User
            description: Creates a user and then sends a generated password email
            requestBody:
              description: A user information object
            requestModels:
              application/json: PutDocumentRequest
            pathParams:
              - name: username
                description: The username for a user to create
                schema:
                  type: string
                  pattern: '^[-a-z0-9_]+$'
            queryParams:
              - name: membershipType
                description: The user's Membership Type
                schema:
                  type: string
                  enum:
                    - premium
                    - standard
            cookieParams:
              - name: SessionId
                description: A Session ID variable
                schema:
                  type: string
            methodResponses:
              - statusCode: 201
                responseBody:
                  description: A user object along with generated API Keys
                responseModels:
                  application/json: PutDocumentResponse
              - statusCode: 500
                responseBody:
                  description: An error message when creating a new user
                responseModels:
                  application/json: ErrorResponse

custom:
  documentation:
    title: 'a title'
    version: '1.2'
    description: 'a description'
    servers:
      - url: 'https://example.com'
        description: 'Dev server'
    security:
      - name: auth
        authorizerName: customAuth
        type: http
        scheme: bearer
    models:
      - name: GetResponse
        description: Response
        contentType: application/json
        tsSchema:
          filePath: test/project/models/GetResponse.ts
          typeName: GetResponse

      - name: ErrorResponse
        description: This is an error
        contentType: application/json
        schema: ${file(test/project/models/ErrorResponse.json)}

      - name: PutDocumentResponse
        description: PUT Document response model (external reference example)
        contentType: application/json
        schema: ${file(test/project/models/PutDocumentResponse.json)}

      - name: PutDocumentRequest
        description: PUT Document request model (inline example)
        contentType: application/json
        schema:
          $schema: http://json-schema.org/draft-04/schema#
          properties:
            SomeObject:
              type: object
              properties:
                SomeAttribute:
                  type: string