Unrecognized property ‘documentation’

[ping2ravi]

NOTE:

1. This issue is coming in documentation plugin but its caused by serverless version 2.6.0, its not caused by plugin itself
2. I have already discussed it on plugin github issue: Unrecognized property ‘documentation’ deliveryhero/serverless-aws-documentation#166
3. I am creating the issue here after discussing it on serverless forum https://forum.serverless.com/t/unrecognized-property-documentation/12885

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 in serverless section below

also under custom i have Models defined properly.

This was working until serveress version 2.5.0 but when upgraded to 2.8.0 it started giving out following errors.

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

I looked into previous releases of serverless and 2.6.0 release caught my attention as its adding a schema validation for http event type and it doesnt handle this particular plugin yaml tags.
To be more specific this pull request has broken it

#8301

I rolled back my environment to 2.5.0 and it started working again

Working ENV (No issue)

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

Problematic ENV (causes unrecognized property ‘documentation’)

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

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

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

serverless.yml

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

sls deploy output

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

Installed version

Framework Core: 2.8.0
Plugin: 4.1.1
SDK: 2.3.2
Components: 3.2.3

[fredericbarthelet]

Hi @ping2ravi , thanks for reporting your issue.

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]

This issue is about same issue as we discuss at #8422, I'm going to close it, and let's follow discussion over there.

[medikoo]

Duplicate of #8422

[fredericbarthelet]

@medikoo this issue is not a duplicate from #8422
#8422 solved serverless-plugin-thundra plugin requirements regarding function property.

serverless-aws-documentation plugin requires the ability to add property on existing event schema provisioned with aws plugin (actually core to serverless repo), like the http trigger type in the example detailed in this issue. More specificaly, they want to extend it with the documentation property.

Made a PR to show you what I mean

[medikoo]

@fredericbarthelet thanks for pointing, in that case we may treat it as duplicate of #8458

[shubsaini09]

@fredericbarthelet @medikoo Do we have a fix for this in place?

[medikoo]

@shubsaini09 check deliveryhero/serverless-aws-documentation#166

[mfadhili]

this issue has a solution over at stack
https://stackoverflow.com/questions/49133294/request-validation-using-serverless-framework
To enable requests validation one need is to add the following to the serverless.yml:

HttpHandler:
    handler: src/lambda/http/create.handler
    events:
      - http:
          method: post
          path: items
          request:
            schemas:
              application/json: ${file(models/create-todo-model.json)}