search

deliveryhero / serverless-aws-documentation

Serverless 1.0 plugin to add documentation and models to the serverless generated API Gateway
MIT License
309 stars 148 forks source link

No responses not set for endpoints #17

Closed dperjar closed 7 years ago

dperjar commented 7 years ago

I'm working on a second project using the serverless-aws-documentation plugin 0.5.6 and running into an issue where response models are not being set for my serverless endpoints.

Request models are present but the Responses object is missing when I "Export as Swagger" in API Gateway. All of my models have been imported in the "Models" section of API Gateway but the response models are not included in the Swagger file. There are no entries for "Method Response" when viewing the endpoint in the API Gateway Resources pane.

I've been able to use this plugin successfully on version 0.5.2 and downgraded to try that version, which worked. It set method responses successfully and the exported Swagger included my responses as expected. I haven't tested other versions .

Here's the serverless.yml I'm using to produce the incorrect behavior on 0.5.6... I've trimmed it down to just one endpoint in the process of debugging and for clarity.

#Serverless Framework 1.5.1
service: AuthDemo

provider:
  name: aws
  runtime: nodejs4.3
  memorySize: 128
  cfLogs: true

functions:
  signup:
    handler: handler.signup
    events:
      - http:
          path: signup
          method: post
          documentation:
            summary: "Signup"
            description: ""
            requestBody:
              description: ""
            requestHeaders:
            methodResponses:
              -
                statusCode: 200
                responseBody:
                  description: "Response body description"
                responseModels:
                  "application/json": "signupresponse"
              -
                statusCode: 400
                responseModels:
                  "application/json": "errorresponse"
            requestModels:
              "application/json": "signuprequest"

plugins:
  - serverless-aws-documentation

custom:
  documentation:
    summary: 'Auth Demo Api'
    description: ''
    authorizers:
      -
        name: "cognitoAuthDemo"
        description: ""
    resources:
      -
        path: "signup"
        description: "Signup a new user"
    models:
      -
        name: "errorresponse"
        description: "Error Response"
        contentType: "application/json"
        schema:
          type: object
          properties:
            message:
              type: string
          required:
            - message
      -
        name: "signupresponse"
        description: "Signup Response"
        contentType: "application/json"
        schema:
          type: object
          properties:
            email:
              type: string
              format: email
          required:
            - email
      -
        name: "signuprequest"
        description: "Signup Request"
        contentType: "application/json"
        schema:
          type: object
          properties:
            email:
              type: string
              format: email
            password:
              type: strinZ
              minLength: 8
          required:
            - email
            - password

Here's the Swagger yaml exported after serverless deploy, note empty responses: {}

---
swagger: "2.0"
info:
  version: "2017-01-23T21:39:47Z"
  title: "dev-AuthDemo"
host: "toknhu6au3.execute-api.us-east-1.amazonaws.com"
basePath: "/dev"
schemes:
- "https"
paths:
  /signup:
    post:
      consumes:
      - "application/json"
      parameters:
      - in: "body"
        name: "signuprequest"
        required: true
        schema:
          $ref: "#/definitions/signuprequest"
      responses: {}
definitions:
  signuprequest:
    type: "object"
    required:
    - "email"
    - "password"
    properties:
      password:
        type: "string"
        minLength: 8
      email:
        type: "string"
        format: "email"
tchock commented 7 years ago

Can you try upgrading to version 0.5.4? It could be that this bug has to do with the method responses. This could narrow down the problem that you are having.

dperjar commented 7 years ago

0.5.4 Seems fine and produces correct output as well.

There is one other thing I noticed... and this may just be a different issue because it happens across all versions, but I have an endpoint using the lambda integration rather than the default proxy integration and it has response codes in the output (more than the ones I've defined, in fact) but has no models assigned to those responses.

The .yml for that endpoint looks like

  protectedResource:
    handler: handler.protectedResource
    events:
      - http:
          path: protectedresource
          method: get
          integration: lambda
          authorizer:
              name: cognitoAuthDemo
              arn: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
              claims:
                - email
              documentation:
                summary: ""
                description: ""
                requestBody:
                  description: ""
                requestHeaders:
                requestModels:
                  "application/json": "protectedresourcerequest"
                methodResponses:
                  -
                    statusCode: 200
                    responseModels:
                      "application/json": "protectedresourceresponse"
                  -
                    statusCode: 400
                    responseModels:
                      "application/json": "errorresponse"
                  -
                    statusCode: 502
                    responseModels:
                      "application/json": "errorresponse"

And the Swagger export looks like...

  /protectedresource:
    get:
      consumes:
      - "application/json"
      - "application/x-www-form-urlencoded"
      responses:
        200:
          description: "200 response"
        422:
          description: "422 response"
        400:
          description: "400 response"
        500:
          description: "500 response"
        401:
          description: "401 response"
        502:
          description: "502 response"
        403:
          description: "403 response"
        404:
          description: "404 response"
        504:
          description: "504 response"
      security:
      - 1_CTG7R8Npn: []

I'm guessing this plugin isn't responsible for creating those extra responses, but I haven't tried deploying with the plugin uninstalled. I'm having to use the lambda integration for that endpoint because the newly added Serverless support for Cognito authorizer doesn't support the proxy integration. I'd be interested in knowing if this is a bug, not supported, or perhaps to be supported in a future release.

Thanks for your help.

cdichiara commented 7 years ago

Ah ... I'm glad I swung by.

I have a regression in v0.5.6 that looks like this.

Here's what cloudformation-template-update-stack.json looks like for v0.5.5:

    "ApiGatewayMethodUsersPost": {
      "Type": "AWS::ApiGateway::Method",
      "Properties": {
        "HttpMethod": "POST",
        "RequestParameters": {},
        "ResourceId": {
          "Ref": "ApiGatewayResourceUsers"
        },
        "RestApiId": {
          "Ref": "ApiGatewayRestApi"
        },
        "AuthorizationType": "NONE",
        "Integration": {
          "IntegrationHttpMethod": "POST",
          "Type": "AWS_PROXY",
          "Uri": {
            "Fn::Join": [
              "",
              [
                "arn:aws:apigateway:",
                {
                  "Ref": "AWS::Region"
                },
                ":lambda:path/2015-03-31/functions/",
                {
                  "Fn::GetAtt": [
                    "ClientApiLambdaFunction",
                    "Arn"
                  ]
                },
                "/invocations"
              ]
            ]
          }
        },
        "MethodResponses": [
          {
            "StatusCode": 200,
            "ResponseModels": {
              "application/json": "userCreateResponse"
            }
          },
          {
            "StatusCode": 400,
            "ResponseModels": {
              "application/json": "userCreateResponse"
            }
          },
          {
            "StatusCode": 500,
            "ResponseModels": {
              "application/json": "userCreateResponse"
            }
          }
        ],
        "RequestModels": {
          "application/json": "userCreateRequest"
        }
      },
      "DependsOn": [
        "userCreateResponseModel",
        "userCreateRequestModel"
      ]
    },

Here's what it looks like for v0.5.6:

    "ApiGatewayMethodUsersPost": {
      "Type": "AWS::ApiGateway::Method",
      "Properties": {
        "HttpMethod": "POST",
        "RequestParameters": {},
        "ResourceId": {
          "Ref": "ApiGatewayResourceUsers"
        },
        "RestApiId": {
          "Ref": "ApiGatewayRestApi"
        },
        "AuthorizationType": "NONE",
        "Integration": {
          "IntegrationHttpMethod": "POST",
          "Type": "AWS_PROXY",
          "Uri": {
            "Fn::Join": [
              "",
              [
                "arn:aws:apigateway:",
                {
                  "Ref": "AWS::Region"
                },
                ":lambda:path/2015-03-31/functions/",
                {
                  "Fn::GetAtt": [
                    "ClientApiLambdaFunction",
                    "Arn"
                  ]
                },
                "/invocations"
              ]
            ]
          }
        },
        "MethodResponses": [],
        "RequestModels": {
          "application/json": "userCreateRequest"
        }
      },
      "DependsOn": [
        "userCreateRequestModel"
      ]
    },

With no change to serverless.yml in between. Just let me know if you need more information to reproduce this - I'm willing to send you my serverless.yml privately, I just don't know if publishing it publicly here will expose our project to any risk.

Thanks!

tchock commented 7 years ago

@dperjar, @cdichiara, I think I fixed it. Can you please have a look at #18? Would be cool if you can add the commit in this PR to your project and try it out. Hopefully this fixes your problems.