Fix for requestBody and parameters

[jhaagmans]

Edited the original fix by @David-Sellen (#24) to support parameters again. Hope this can get merged soon, as an important part of what we use this plugin for (parameter and request body documentation) now doesn't work.

[kzhou57]

Tested it, it doesn't sound working.

[jhaagmans]

Could you elaborate? Running the example serverless.yml with the current version of the npm package yields:

openapi: 3.0.0components:
schemas:
PutDocumentRequest:
properties:
SomeObject:
type: objectproperties:
SomeAttribute:
type: stringsecuritySchemes: {}info:
title: ''description: ''version: 712334c8-7b29-46c5-9e93-cd7acb6b8825paths:
/create:
post:
operationId: createUsersummary: Create Userdescription: Creates a user and then sends a generated password emailresponses:
'201':
description: A user object along with generated API Keyscontent:
application/json:
schema:
$ref: '#/components/schemas/PutDocumentResponse''500':
description: An error message when creating a new usercontent:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

Mind that all parameters and the RequestBody are missing.

With this fix, this is the result:

openapi: 3.0.0components:
schemas:
ErrorResponse:
title: JSON API Schemadescription: >- This is a schema for responses in the JSON API format. For more, see http://jsonapi.orgtype: objectrequired:
- errorsproperties:
errors:
type: arrayitems:
type: objectproperties:
id:
description: >- A unique identifier for this particular occurrence of the problem.type: stringlinks:
description: >- A resource object **MAY** contain references to other resource objects ("relationships"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.type: objectproperties:
self:
description: >- A `self` member, whose value is a URL for the relationship itself (a "relationship URL"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.type: stringformat: urirelated:
description: >- A link **MUST** be represented as either: a string containing the link's URL or a link object.oneOf:
- description: A string containing the link's URL.type: stringformat: uri
- type: objectrequired:
- hrefproperties:
href:
description: A string containing the link's URL.type: stringformat: urimeta:
description: >- Non-standard meta-information that can not be represented as an attribute or relationship.type: objectadditionalProperties: trueadditionalProperties: truestatus:
description: >- The HTTP status code applicable to this problem, expressed as a string value.type: stringcode:
description: >- An application-specific error code, expressed as a string value.type: stringtitle:
description: >- A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.type: stringdetail:
description: >- A human-readable explanation specific to this occurrence of the problem.type: stringsource:
type: objectproperties:
pointer:
description: >- A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].type: stringparameter:
description: >- A string indicating which query parameter caused the error.type: stringmeta:
description: >- Non-standard meta-information that can not be represented as an attribute or relationship.type: objectadditionalProperties: trueadditionalProperties: falseuniqueItems: truemeta:
description: >- Non-standard meta-information that can not be represented as an attribute or relationship.type: objectadditionalProperties: truelinks:
description: >- A resource object **MAY** contain references to other resource objects ("relationships"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.type: objectproperties:
self:
description: >- A `self` member, whose value is a URL for the relationship itself (a "relationship URL"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.type: stringformat: urirelated:
description: >- A link **MUST** be represented as either: a string containing the link's URL or a link object.oneOf:
- description: A string containing the link's URL.type: stringformat: uri
- type: objectrequired:
- hrefproperties:
href:
description: A string containing the link's URL.type: stringformat: urimeta:
description: >- Non-standard meta-information that can not be represented as an attribute or relationship.type: objectadditionalProperties: trueadditionalProperties: trueadditionalProperties: falsePutDocumentResponse:
title: Empty Schematype: objectPutDocumentRequest:
properties:
SomeObject:
type: objectproperties:
SomeAttribute:
type: stringsecuritySchemes: {}info:
title: ''description: ''version: e9860c9e-d888-47fc-9068-6094d45e0550paths:
'/create/{username}':
post:
operationId: createUsersummary: Create Userdescription: Creates a user and then sends a generated password emailrequestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutDocumentRequest'description: A user information objectparameters:
- name: usernamein: pathdescription: The username for a user to createrequired: trueschema:
type: stringpattern: '^[-a-z0-9_]+$'
- name: membershipTypein: querydescription: The user's Membership Typerequired: falseallowEmptyValue: falseschema:
type: stringenum:
- premium
- standard
- name: SessionIdin: cookiedescription: A Session ID variablerequired: falseschema:
type: stringresponses:
'201':
description: A user object along with generated API Keyscontent:
application/json:
schema:
$ref: '#/components/schemas/PutDocumentResponse''500':
description: An error message when creating a new usercontent:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

What did you test and what did your test yield? The only thing this PR is targeted at, is making sure the RequestBody and parameters are working again.

You probably need to fix the pathParameter in the example, as there is no actual pathParameter in the example path, but the error for that is clear.

[adambartholomew]

I can also confirm that *params and the requestModel properties are being ignored in the serverless.yml configuration. The DefinitionGenerator needs to check for a value in the documentationConfig, not the being-generated operationObj.

[adambartholomew]

@nfour Any chance you can look into this further? It seems like a lot of users are running into this blocker.

[nfour]

@adambartholomew

This repo has naturally regressed into a state of deprecation as we at Temando have decided not to make use of this plugin.

The reasoning being that it is undesirable to couple directly to Serverless and instead we've opted for other Open Api generation methods.

I'd recommend someone forks the project and publishes a new package as I don't see us putting effort into this plugin going forward.

Sorry :(

[snoblenet]

If this plugin is deprecated then you should update the repo Read Me and you should advise Serverless to stop linking to this plugin.