Unrecognized property ‘documentation’

[ping2ravi]

In my server.yml i am defining API documentation as per https://www.serverless.com/plugins/serverless-aws-documentation

I have documentation plugin installed and added like this

plugins:
  - serverless-aws-documentation

I have function defined like this

create-company:
    handler: bin/create-company
    events:
      - http:
          path: v1/owner/{ownerId}/company
          method: POST
          documentation:
            summary: Create a new Company
            pathParams:
              -
                name: "ownerId"
                description: "Owner ID"
                required: true
                type: string
            requestHeaders:
              -
                name: "Authorization"
                description: "Bearer token"
                required: true
                type: string
            requestModels:
               "application/json": CreateCompanyRequest
            methodResponses:
              -
                statusCode: '200'
                responseModels:
                  "application/json": "CreateCompanyResponse"
                responseHeaders:
                  -
                    name: Content-Type
                    description: Content Type
                    type: string
    package:
      exclude:
        - ./**
      include:
        - ./bin/create-company

also under custom i have Models defined properly.

Until Few days back it was working fine and suddenly it stopped working, from git i checkout my few days old version of project and tried it, thats also failing with following error

Serverless: at ‘functions[‘create-company’].events[0].http’: unrecognized property ‘documentation’

I am stuck at this problem for few days, any help will be appreciated

My Current env looks like this

> sls version
Framework Core: 2.8.0
Plugin: 4.1.1
SDK: 2.3.2
Components: 3.2.3

Not sure how to solve this issue. I have tried going back to previous version for serverless(2.7.0) as well as documentation plugin(1.0.0, 1.0.1). i have checked for typo errors but its happening in my 3 serverless projects

[JoshuaJWilborn]

Having the same issue after updating packages. Will share solution if I find one.

[ping2ravi]

It Seems like Serverless code issue rather then this plugin issue, so need to be fixed with in server less and closing this one here

First Workaround

Rollback your serverless environment to version 2.5.0 (when writing this current version is 2.8.0, 2.6.0 introduced this issue)

Following env is tested and working good.

> sls -v
Framework Core: 2.5.0
Plugin: 4.1.1
SDK: 2.3.2
Components: 3.2.5

I created this Docker image with serverles and aws cli V2 and it work perfectly, from now onwards will keep using this image until its fixed by serverless and may be then go back to latest serverless version.

FROM node:14.14.0-buster-slim
RUN whoami
RUN npm install -g [email protected]; serverless -v
RUN apt-get update -y; apt-get install curl -y; apt-get install zip -y
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"; unzip awscliv2.zip; ./aws/install
RUN rm -fR awscliv2.zip
RUN npm install serverless-aws-documentation --save-dev
RUN npm install serverless-domain-manager --save-dev
RUN npm install serverless-plugin-split-stacks --save-dev
RUN apt-get install --reinstall make
RUN aws --version

https://hub.docker.com/repository/docker/ping2ravi/aws-serverless/

Problem :

I went through the Serverless releases and one particular release/Commit caught my eyes 2.6.0

Aws http event schema #8301

Recently schema for http has been created which doesn't include 'documentation' tag/key. Check the Exact commit lines.

https://github.com/serverless/serverless/pull/8301/files#diff-d12e6ea1f3044bb11f07be72a2d9eafa31f8174ca5ea26ce5122bfd8dd232c67L30

I am not into JS development but i hope this can be prioritised/fixed quickly by serverless devs or someone who knows this code base.

I have created this issue in serverless github issue tracker for further tracking :

https://forum.serverless.com/t/unrecognized-property-documentation/12885/2

[ping2ravi]

It seems it need to be fixed with in this plugin..

serverless/serverless#8438 (comment)

[ping2ravi]

The Serverless framework does indeed implement an http event validation since 2.6.0, which does not include documentation property.

The http.documentation property is solely the scope of the serverless-aws-documentation plugin.

All plugin developers are encouraged to include JSON schema definition of their properties for validation, see https://www.serverless.com/framework/docs/providers/aws/guide/plugins/#extending-validation-schema for more info.

As of today, you can add in serverless.yaml root configValidationMode: off and it will disable display of those error messages. You however won't benefit from JSON schema validation for other properties of your service file.

Adding plugin specific variables to the schema validation using documentation linked above would be the way to go to ensure no warning message are displayed anymore. You can for exemple add the following to https://github.com/deliveryhero/serverless-aws-documentation/blob/master/src/index.js

class ServerlessAWSDocumentation {
  constructor(serverless, options) {
    this.serverless = serverless;

    const serverlessAWSDocumentationCustomPropSchema = {
      properties: {
        documentation: { 
          type: 'object' ,
          properties: { //... }
      },
      required: ['documentation'],
    };

    // Attach your piece of schema to main schema
    serverless.configSchemaHandler.defineCustomProperties(serverlessAWSDocumentationCustomPropSchema);

The API limits plugin addition to custom and provider service properties. You can also define your own new function events. But there is no way currently to enrich an existing Serverless core event with additional properties.

@medikoo do you think, for this use case for example, that an additional method defineEventProperties should be implemented ? The idea would be to allow serverless-aws-documentation plugin to enrich http schema with their documentation property schema:

serverless.configSchemaHandler.defineEventProperties('aws', 'http', {
  properties: {
    documentation: { 
      type: 'object',
      properties: {
        //...
      }
  }
});

[medikoo]

@medikoo do you think, for this use case for example, that an additional method defineEventProperties should be implemented ?

I believe yes. We need defineFunctionEventProperties please open a request on Framework side, we'll also be happy to take in PR that adds it.

[Benzer1406]

Have the same issue

[timfulmer]

+1

[ozanyurtsever]

Having the same issue with version 2.8.0

[medikoo]

defineFunctionEventProperties was introduced in Framework, please check: https://www.serverless.com/framework/docs/providers/aws/guide/plugins#definefunctioneventproperties-helper

Having that this plugin can introduce needed schema

[jinman]

This plugin is not maintained anymore as per its readme. Any suggestions or best practices on best way to move forward having the API documentation generated from serverless.yml file? Are there any other plugin we should use? What is the openapi or any other documentation best practices for 3.0.0?