temando / serverless-openapi-documentation

Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration
MIT License
93 stars 127 forks source link

Fix for requestBody and parameters #27

Closed jhaagmans closed 5 years ago

jhaagmans commented 6 years ago

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 commented 6 years ago

Tested it, it doesn't sound working.

jhaagmans commented 6 years ago

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

openapi: 3.0.0
components:
  schemas:
    PutDocumentRequest:
      properties:
        SomeObject:
          type: object
          properties:
            SomeAttribute:
              type: string
  securitySchemes: {}
info:
  title: ''
  description: ''
  version: 712334c8-7b29-46c5-9e93-cd7acb6b8825
paths:
  /create:
    post:
      operationId: createUser
      summary: Create User
      description: Creates a user and then sends a generated password email
      responses:
        '201':
          description: A user object along with generated API Keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutDocumentResponse'
        '500':
          description: An error message when creating a new user
          content:
            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.0
components:
  schemas:
    ErrorResponse:
      title: JSON API Schema
      description: >-
        This is a schema for responses in the JSON API format. For more, see
        http://jsonapi.org
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                description: >-
                  A unique identifier for this particular occurrence of the
                  problem.
                type: string
              links:
                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: object
                properties:
                  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: string
                    format: uri
                  related:
                    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: string
                        format: uri
                      - type: object
                        required:
                          - href
                        properties:
                          href:
                            description: A string containing the link's URL.
                            type: string
                            format: uri
                          meta:
                            description: >-
                              Non-standard meta-information that can not be
                              represented as an attribute or relationship.
                            type: object
                            additionalProperties: true
                additionalProperties: true
              status:
                description: >-
                  The HTTP status code applicable to this problem, expressed as
                  a string value.
                type: string
              code:
                description: >-
                  An application-specific error code, expressed as a string
                  value.
                type: string
              title:
                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: string
              detail:
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem.
                type: string
              source:
                type: object
                properties:
                  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: string
                  parameter:
                    description: >-
                      A string indicating which query parameter caused the
                      error.
                    type: string
              meta:
                description: >-
                  Non-standard meta-information that can not be represented as
                  an attribute or relationship.
                type: object
                additionalProperties: true
            additionalProperties: false
          uniqueItems: true
        meta:
          description: >-
            Non-standard meta-information that can not be represented as an
            attribute or relationship.
          type: object
          additionalProperties: true
        links:
          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: object
          properties:
            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: string
              format: uri
            related:
              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: string
                  format: uri
                - type: object
                  required:
                    - href
                  properties:
                    href:
                      description: A string containing the link's URL.
                      type: string
                      format: uri
                    meta:
                      description: >-
                        Non-standard meta-information that can not be
                        represented as an attribute or relationship.
                      type: object
                      additionalProperties: true
          additionalProperties: true
      additionalProperties: false
    PutDocumentResponse:
      title: Empty Schema
      type: object
    PutDocumentRequest:
      properties:
        SomeObject:
          type: object
          properties:
            SomeAttribute:
              type: string
  securitySchemes: {}
info:
  title: ''
  description: ''
  version: e9860c9e-d888-47fc-9068-6094d45e0550
paths:
  '/create/{username}':
    post:
      operationId: createUser
      summary: Create User
      description: Creates a user and then sends a generated password email
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutDocumentRequest'
        description: A user information object
      parameters:
        - name: username
          in: path
          description: The username for a user to create
          required: true
          schema:
            type: string
            pattern: '^[-a-z0-9_]+$'
        - name: membershipType
          in: query
          description: The user's Membership Type
          required: false
          allowEmptyValue: false
          schema:
            type: string
            enum:
              - premium
              - standard
        - name: SessionId
          in: cookie
          description: A Session ID variable
          required: false
          schema:
            type: string
      responses:
        '201':
          description: A user object along with generated API Keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutDocumentResponse'
        '500':
          description: An error message when creating a new user
          content:
            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 commented 6 years ago

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 commented 6 years ago

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

nfour commented 5 years ago

@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 commented 3 years ago

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