conqa / serverless-openapi-documentation Goto Github PK

I have custom/documentation section of serverless.yml defined as follows:

version: ...
title: ...
description: ...
tags:
  - name: public
    description: API endpoints not requiring authentication
  - name: user-level
  - name: ...
models:
  - ...

with ... being properly replaced to meaningful values. After compilation I don't see tags section in the resulting openapi.yml file on the root level.

Note: function-level tags definition are properly transferred.

In the property documentation/models/schema I'm pointing to a JSON schema file of the object supposed to be sent in the request body:

models:
    - schema: ${file(models/test.json)}
      name: 'Tester'
      description: 'Esquema Tester Object'
      contentType: 'application/json'

Even though I declared some required fields in the schema, the object is sent when those fields are absent. The request shouldn't be executed successfully under that scenario.

It works properly if I also declare the schema in the serverless.yml (functions/events/Http/request):

events:
      - http:
          path: /tester
          method: post
          integration: lambda
          request:
            schema:
              application/json: ${file(models/test.json)}
            template:
              application/json: $input.json('$')
          documentation: ${file(my-project-api.doc.yml):endpoints.tester}

But that configuration is not desirable since I have to set the request schema in two places, so the risk to break things in big/complex projects are very high.

test schema with some required fields:

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Test",
  "description": "Tester",
  "type": "object",
  "required": [ "age", "name" ],
  "properties": {

    "name": {
      "type": "string",
      "description": "names"
    },
    "age" : {
      "type": "integer",
      "description": "age"
    },
    "is": {
      "type": "boolean",
      "description": "type"
    }
  }
}

It would be nice to support the "security" object at 'function' level.
See 'Step 2. Applying security' at https://swagger.io/docs/specification/authentication/

It's already managed in the 'custom' section, but will then apply to the whole API. Overloading at the function level would be useful.

Outline changes from original package

Copy of an issue from original repo posted by @ecolman

Original text:

Is there any way to have the securitySchemes picked up through the config? I took a look at the code, but it seems like the securitySchemes is always set to {}. Using a token based header to validate the user.

https://github.com/temando/serverless-openapi-documentation/blob/master/src/DefinitionGenerator.ts#L42

Original issue: temando#20

The very old version of swagger2openapi uses should (ShouldJS) which mutates the global Object. Normally this is supposed to only be used in testing but this is being applied all the time.

Fixed here: Mermade/oas-kit#83
and published in [email protected]

This plugin doesn't seem to support HttpApi, i.e.

functions:
list:
handler: src/handler.list
events:
- httpApi:
path: /subject
method: GET
documentation: ${file(documentation.yml):endpoints.list}

Just gets ignored when generating docs. Are there plans to support it?

How could we achieve our goal? anyone please help...

My goal is to have these, inside openapi.json:

These is what I did on the yml file, but it is not updating the openapi.json:

The schema with allow null not handled
{ "type": ["string", "null"] }
According to https://swagger.io/docs/specification/data-models/data-types/

null should be handled as property nullabel: true

• travis deploy needs to be updated
• two deploy jobs - release @latest and release @next
• @latest (npm publish) should be released on tags matching only tags of format v<Maj>.<Minor>.<Patch>, such asv1.0.0
• @next ( npm publish --tag next) should be released on tags matching only tags of format v<Maj>.<Minor>.<Patch>-<Prerelease>, such asv1.0.0-alpha or v1.0.0-1

Related travis documentation:

• https://docs.travis-ci.com/user/deployment#conditional-releases-with-on

It is not documented.

• rename build folder to dist
• ship source alongside dist
• no longer cd into a build folder to publish
• include proper main entry in package.json

Currently headers and parameters only support schema defined in serverless file or json schema imported using serverless ${file(<json-schema>)} syntax.

Need to add support for importing schemas by specifying a path

I cant thank enough every single collaborator in this fork. We started using serverless a few months ago and this was one of the last pieces of the puzzle.

My only concern is the schema-validation inside of AWS works with this package ? or do we still have to use serverless-aws-documentation to validate everything ?

Thanks.

I am trying to use the tag - 1.1.0 along with other plugins in my serverless.yml file.

plugins:
  - serverless-domain-manager
  - serverless-plugin-typescript
  - serverless-dynamodb-local
  - serverless-prune-plugin
  - serverless-offline
  - @conqua/serverless-openapi-documentation

Error:

  Serverless Error ---------------------------------------
 
  Serverless plugin "@conqua/serverless-openapi-documentation" not found. Make sure it's installed and listed in the "plugins" section of your serverless config file.

I also tried installing the plugin using my package.json and referencing using the localPath options for plugins

plugins:
- localPath: './node_modules/@conqua/serverless-openapi-documentation'
- modules:
  - serverless-domain-manager
  - serverless-plugin-typescript
  - serverless-dynamodb-local
  - serverless-prune-plugin
  - serverless-offline

But I receive the below error :

Type Error ---------------------------------------------
 
  TypeError: [object Object] is not a string
      at module.exports (/Users/chetanpawar/Work-Related/kubernetes/kube-deploy-dir/helm/organizational-socialization/node_modules/type/lib/resolve-exception.js:12:8)

I tried executing the below command with both ways :

serverless openapi generate -o openapi.yaml

Can anyone help here to specify the right option to use this fork of the plugin to work with the other core plugins ?