serverless-aws-documentation
serverless-aws-documentation copied to clipboard
deliveryhero
No Method Response integration, v1.0
Whenever I am trying to deploy my serverless.yml, I don't see the method responses in my AWS Console:
However, all the models are created properly:
Environment
$ sls -v
Framework Core: 1.74.1 (standalone)
Plugin: 3.6.14
SDK: 2.3.1
Components: 2.31.6
package.json
{
"name": "secret",
"description": "",
"version": "0.1.0",
"dependencies": {},
"devDependencies": {
"serverless-aws-documentation": "^1.1.0",
"serverless-reqvalidator-plugin": "^1.0.3"
}
}
serverless.yml
service: secret
frameworkVersion: ">=1.50.0 <2.0.0"
plugins:
- serverless-reqvalidator-plugin
- serverless-aws-documentation
custom:
documentation:
api:
info:
title: Secret
description: |
**Secret** description with *[Common Mark](https://commonmark.org/help/)* It can be used in other descriptions too.
version: 1.0.1-dev5 # change it to unique values so that documentation is upgraded
tags:
- name: products
description: Product-related API
models:
- name: ProductListResponse
contentType: application/json
schema:
type: object
required: [products]
additionalProperties: false
properties:
products:
$ref: '{{model: ProductFromList}}'
- name: ProductFromList
contentType: application/json
schema:
title: The Product general information
type: object
required:
- id
- name
- image_name
- image_url
- disabled
additionalProperties: false
# example:
# id: 1234567890
# name: Super Product 001 Small Black
# image_name: my_image.png
# image_url: presigned_url_in_png_format
# disabled: false
properties:
id:
type: integer
format: int64
# example: '3333333333'
name:
type: string
# example: Super Product 002 Blue
disabled:
type: boolean
# example: true
image_name:
type: string
pattern: '^[\\w-]+\\.png$'
# example: my_image.png
image_url:
allOf:
- $ref: '{{model: Uri}}'
# - example: https://mega-bucket.s3.amazonaws.com/1111111/13146541156462.png?AWSAccessKeyId=ASDFASDF&Signature=f3j4l5%aFsASDdff&x-amz-security-token=XcMpI6tJVsudqbT&-Expires=1594209643
- name: Uri
contentType: application/json
schema:
type: string
pattern: ^([a-z][a-z0-9+.-]*):(?:\\\/\\\/((?:(?=((?:[a-z0-9-._~!$&\'()*+,;=:]|%[0-9A-F]{2})*))(\\3)@)?(?=(\\[[0-9A-F:.]{2,}\\]|(?:[a-z0-9-._~!$&\'()*+,;=]|%[0-9A-F]{2})*))\\5(?::(?=(\\d*))\\6)?)(\\\/(?=((?:[a-z0-9-._~!$&\'()*+,;=:@\\\/]|%[0-9A-F]{2})*))\\8)?|(\\\/?(?!\\\/)(?=((?:[a-z0-9-._~!$&\'()*+,;=:@\\\/]|%[0-9A-F]{2})*))\\10)?)(?:\\?(?=((?:[a-z0-9-._~!$&\'()*+,;=:@\\\/?]|%[0-9A-F]{2})*))\\11)?(?:#(?=((?:[a-z0-9-._~!$&\'()*+,;=:@\\\/?]|%[0-9A-F]{2})*))\\12)?$
- name: CommonGeneralError
contentType: application/json
schema:
type: object
required:
- message
additionalProperties: true
properties:
message:
type: string
# example:
# message: Internal Server Error
commonModelSchemaFragments:
CommonGeneralError500:
statusCode: '500'
responseBody: Common general 400 error
responseModels:
application/json: CommonGeneralError
CommonGeneralError400:
statusCode: '500'
responseBody: Common general 400 error
responseModels:
application/json: CommonGeneralError
resources:
Resources:
all:
Type: 'AWS::ApiGateway::RequestValidator'
Properties:
Name: all
RestApiId:
Ref: ApiGatewayRestApi
ValidateRequestBody: true
ValidateRequestParameters: true
provider:
name: aws
runtime: python3.8
region: us-east-1
apiName: secret
stackName: secret
deploymentPrefix: secret
endpointType: regional
apiKeys:
- secret-key
apiGateway:
apiKeySourceType: HEADER
metrics: true
# tracing:
# apiGateway: true
# lambda: true
logs:
restApi:
accessLogging: false
executionLogging: false
fullExecutionData: false
roleManagedExternally: true
role: arn:aws:iam::123412341234:role/secret-1
reqValidatorName: all
package:
individually: true
functions:
secret:
name: secrete
handler: path/to-my-directory/secret.py
role: arn:aws:iam::123412341234:role/secret-1
disableLogs: false
layers:
- arn:aws:lambda:us-east-1:123412341234:layer:Layer1:1
- arn:aws:lambda:us-east-1:123412341234:layer:Layer2:1
exclude:
- ./**
include:
- path/to-my-directory/secret.py
- common/**
events:
- http:
path: /products
method: get
documentation:
tags: [products]
summary: Lists all products
methodResponses:
- statusCode: '200'
responseModels:
application/json: ProductFromList
- ${self:custom.commonModelSchemaFragments.CommonGeneralError400}
- ${self:custom.commonModelSchemaFragments.CommonGeneralError500}
cors: true
private: true
reqValidatorName: all
request:
parameters:
querystrings:
customerId: true
My investigation
I have looked for the usage of methodResponses property within the source code and tried to check if my file is OK. Method addMethodResponses (called at src/documentation.js) seems to work OK since it detects my responses from serverless.yml and adds them to some object. However, they don't seem to reach the AWS.
Additionally, I have tried versions from 0.6 (according to #17), using binary search to leap between the version upwards, but up to 1.1 none of versions even work in my environment (throwing 400 HTTP Error).
I just got this working, some excerpts from my yaml:
<!-- From the custom section -->
documentation:
api:
info:
version: "1"
title: "Site"
description: "Site API"
models:
-
name: "ClientErrorResponse"
description: "Model representing http 4XX client error response"
contentType: "application/json"
schema: ${file(resources/response-model/client-error-response.schema.json)}
-
name: "CustomerSiteList"
description: "Model representing list of customer sites"
contentType: "application/json"
schema: ${file(resources/response-model/site-response.schema.json)}
<!-- From the http section of a function -->
documentation:
summary: Get all sites for a customer
description: Get all sites for a customer denoted by the request parameter customer_id
queryParams:
-
name: customer_id
description: The customer id
required: true
methodResponses:
-
statusCode: "200"
responseBody:
description: "Response body description"
responseModels:
"application/json": "CustomerSiteList"
-
statusCode: "400"
responseModels:
"application/json": "ClientErrorResponse"
Framework Core: 1.68.0
Plugin: 3.6.8
SDK: 2.3.0
Components: 2.30.2
If there is anything else I can inform you of that might help please let me know.
