{"id":15046147,"url":"https://github.com/yndlingsfar/serverless-openapi-integration-helper","last_synced_at":"2025-10-26T02:31:16.326Z","repository":{"id":37099073,"uuid":"354271536","full_name":"yndlingsfar/serverless-openapi-integration-helper","owner":"yndlingsfar","description":"The plugin separates x-amazon-apigateway extension syntax from your openapi3 files","archived":false,"fork":false,"pushed_at":"2023-04-15T06:50:40.000Z","size":695,"stargazers_count":6,"open_issues_count":8,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-30T03:22:48.281Z","etag":null,"topics":["aws-gateway","openapi-specification","openapi3","serverless-framework","serverless-plugin","yml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yndlingsfar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-03T11:15:21.000Z","updated_at":"2023-12-05T09:28:34.000Z","dependencies_parsed_at":"2024-06-19T11:27:30.678Z","dependency_job_id":"db589e23-a7ed-4de0-8501-9f4f2b980ac3","html_url":"https://github.com/yndlingsfar/serverless-openapi-integration-helper","commit_stats":{"total_commits":87,"total_committers":6,"mean_commits":14.5,"dds":0.1724137931034483,"last_synced_commit":"50b127cdd7272364997bd5cf9f3c621ac23982ef"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yndlingsfar%2Fserverless-openapi-integration-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yndlingsfar%2Fserverless-openapi-integration-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yndlingsfar%2Fserverless-openapi-integration-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yndlingsfar%2Fserverless-openapi-integration-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yndlingsfar","download_url":"https://codeload.github.com/yndlingsfar/serverless-openapi-integration-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238247984,"owners_count":19440879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-gateway","openapi-specification","openapi3","serverless-framework","serverless-plugin","yml"],"created_at":"2024-09-24T20:52:46.369Z","updated_at":"2025-10-26T02:31:15.683Z","avatar_url":"https://github.com/yndlingsfar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://npmjs.com/package/serverless-openapi-integration-helper\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/npm/v/serverless-openapi-integration-helper?icon=npm\u0026label=npm@latest\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/serverless-openapi-integration-helper\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/npm/dt/serverless-openapi-integration-helper?icon=npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://packagephobia.now.sh/result?p=serverless-openapi-integration-helper\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/packagephobia/install/serverless-openapi-integration-helper\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/serverless-openapi-integration-helper\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/npm/license/serverless-openapi-integration-helper\"\u003e\u003c/a\u003e\n  \u003cbr/\u003e\n\u003c/p\u003e\n\n_Feedback is appreciated! If you have an idea for how this plugin/library can be improved (or even just a complaint/criticism) then please open an issue._\n\n# Serverless Plugin: AWS Api Gateway integration helper\n\n1. [Overview](#overview)\n1. [Installation \u0026 Setup](#installation--setup)\n1. [Plugin configuration](#plugin-configuration)  \n1. [Usage](#usage)\n1. [Command](#commands)\n1. [CORS Generator](#cors-generator)\n1. [AUTO-MOCK Generator](#auto-mock-generator)\n1. [VALIDATION Generator](#validation-generator)\n1. [PROXY Manager](#proxy-manager)\n1. [Configuration Reference](#configuration-reference)\n1. [Known Issues](#known-issues)\n   1. [Stage Deployment](#stage-deployment)\n   1. [Variable Resolving](#variable-resolving)\n1. [Example](#example)\n1. [Approach to a functional test of schema validation](#approach-to-a-functional-test-of-schema-validation)\n\n# Overview \nThe plugin provides the functionality to merge [OpenApiSpecification files](https://swagger.io/specification/) (formerly known as swagger) with one or multiple YML files containing the the x-amazon-apigateway extensions.\nThere are several use-cases to keep both information separated, e.g. it is needed to deploy different api gateway integrations depending on a stage environment.\n\nWhen dealing with functional tests you do not want to test the production environment, but only a mocking response.\n\n**The plugin supports YML based OpenApi3 specification files only**\n\n## Features\n- Serverless 3.x Support\n- deploy stage dependent x-amazon-apigateway integrations\n- separate infrastructure (aws) from openapi specification\n- use mock integrations for functional testing\n- auto-generating CORS methods, headers and api gateway mocking response\n- hook into package \u0026 deploy lifeCycle and generate combined openApi files on the fly during deployment\n- auto-inject generated openApi file into the Body property of specified API Gateway\n- generate mocking responses without specifying x-amazon-apigateway-integration objects\n- generate request-validation blocks\n- generate all required x-amazon-apigateway-integration objects automatically\n- full proxy generation support with **[NEW]:** feature: [PROXY Manager](#proxy-manager)\n\nSee the **examples** folder for a full working [example](https://github.com/yndlingsfar/serverless-openapi-integration-helper/tree/main/examples)\n\n# Installation \u0026 Setup\n\nRun `npm install` in your Serverless project.\n\n`$ npm install --save-dev serverless-openapi-integration-helper`\n\nAdd the plugin to your serverless.yml file\n\n```yml\nplugins:\n  - serverless-openapi-integration-helper\n```\n# Plugin configuration\nYou can configure the plugin under the key **openApiIntegration**. See\nSee [Configuration Reference](#configuration-reference) for a list of available options\n\nThe value for `openApiIntegration` must be either a single object or an array of objects.\nFor an array of objects, the `apiResourceName` property must be specified in each object to determine\nwhich `Aws::ApiGateway::RestApi` resource to insert the merged API specification into,\nwhile for a single object it's optional and will default to the first found\n`Aws::ApiGateway::RestApi` resource.\n\nThe mapping array must be used to configure where the files containing the **x-amazon-apigateway-integration** blocks are located.\n\n```yml\nopenApiIntegration:\n    package: true #New feature! Hook into the package \u0026 deploy process\n    inputFile: schema.yml\n    mapping:\n       - stage: [dev, prod] #multiple stages\n         path: integrations\n       - stage: test #single stage\n         path: mocks\n```\n\nIn the above example all YML files inside the _integrations_ directory will be processed and merged with the schema.yml file when deploying the dev stage\n```shell\nserverless deploy --stage=dev\n```\n\nTo use a different x-amazon-apigateway to perform functional tests (with mocking responses e.g) the directory mock is processed and merged with the schema.yml file when deploying the test stage\n```shell\nserverless deploy --stage=test\n```\n\n## Multiple APIs\n\nTo handle multiple APIs, supply an array as the value of `openApiIntegrations`\ninstead of a single object, and specify the target `Aws::ApiGateway::RestApi`\nresource for each item using the `apiResourceName` property, and make sure to specify\nunique output files by setting `outputDirectory` and/or `outputFile` uniquely:\n\n```yml\nopenApiIntegration:\n  - package: true\n    inputFile: schema-1.yml\n    apiResourceName: Api1\n    outputFile: api-1.yml\n    mapping:\n      - stage: [dev, prod]\n        path: integrations/api-1\n  - package: true\n    inputFile: schema-2.yml\n    apiResourceName: Api2\n    outputFile: api-2.yml\n    mapping:\n       - stage: [dev, prod]\n         path: integrations/api-2\n\n...\n\nresources:\n  Resources:\n    Api1:\n      Type: AWS::ApiGateway::RestApi\n      Properties:\n        Body: ~ # auto-generated by plugin from schema-1\n\n        ...\n\n    Api2:\n       Type: AWS::ApiGateway::RestApi\n       Properties:\n          Body: ~ # auto-generated by plugin from schema-2\n\n          ...\n```\n\n# Usage\nYou can setup a fully working API GATEWAY with any openApi 3.0 specification file\nFirst create the input file containing the [OpenApiSpecification](https://swagger.io/specification/)\n```yml\n# ./schema.yml\nopenapi: 3.0.0\ninfo:\n  description: User Registration\n  version: 1.0.0\n  title: UserRegistration\npaths:\n  /api/v1/user:\n    post:\n      summary: adds a user\n      requestBody:\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/Customer'\n      responses:\n        '201':\n          description: user created\ncomponents:\n  schemas:\n    Customer:\n      type: object\n      required:\n        - email_address\n        - password\n      properties:\n        email_address:\n          type: string\n          example: test@example.com\n        password:\n          type: string\n          format: password\n          example: someStrongPassword#\n```\n\nThe plugin will generate the **x-amazon-apigateway integrations** objects for all methods that do not have an integration.\n\n```yml\n#generate a file containing a gateway mock integration in the directory /mocks\nserverless integration create --output mocks --type mock --stage=test\n\n#generate a file containing the production integration in the directory integrations/\nserverless integration create --output integrations --type http --stage=prod\n```\n\nSupported types are\n- http_proxy\n- http\n- aws\n- aws_proxy\n- mock\n\n\nThe plugin now generates a merged file during deployment that is automatically injected in your serverless resources\n\n```shell\n#Create OpenApi File containing mocking responses (usable in functional tests) and deploy to ApiGateway\nserverless deploy --stage==test\n```\n\n```shell\n#Create OpenApi File containing the production integration and deploy to ApiGateway\nserverless deploy --stage=prod\n```\n\nThe generated output is automatically injected in the **resources.Resources.YOUR_API_GATEWAY.Properties.Body** property\n```yml\nresources:\n  Resources:\n    ApiGatewayRestApi:\n      Type: AWS::ApiGateway::RestApi\n      Properties:\n        ApiKeySourceType: HEADER\n        Body: ~ #autogenerated by plugin\n        Description: \"Some Description\"\n        FailOnWarnings: false\n        Name: ${opt:stage, self:provider.stage}-some-name\n        EndpointConfiguration:\n          Types:\n            - REGIONAL\n    ApiGatewayDeployment:\n      Type: AWS::ApiGateway::Deployment\n      Properties:\n        RestApiId:\n          Ref: ApiGatewayRestApi\n        StageName: ${opt:stage, self:provider.stage}\n```\n\n# Commands\n\n## Manual merge\nThe generate command can be used independently with\n```yml\nserverless integration merge --stage=dev\n```\nOf course then the API Gateway Body property has to be specified manually\n\n```yml\nresources:\n  Resources:\n    ApiGatewayRestApi:\n      Type: AWS::ApiGateway::RestApi\n      Properties:\n        ApiKeySourceType: HEADER\n        Body: ${file(openapi-integration/api.yml)}\n```\n\n# CORS generator\n\nThe plugin can generate full CORS support out of the box. \n```yml\nopenApiIntegration:\n  cors: true\n  ...\n```\n\nIf enabled, the plugin generates all required OPTIONS methods as well as the required header informations and adds a mocking response to API Gateway. \nYou can customize the CORS templates by placing your own files inside a directory **openapi-integration** (in your project root). The following files can be overwritten:\n\n| Filename        | Description |\n| ------------- |:-------------:| \n| headers.yml    | All headers required for CORS support |\n| integration.yml      | Contains the x-amazon-apigateway-integration block  |\n| path.yml| OpenApi specification for the OPTIONS method       |\n| response-parameters.yml| The response Parameters of the x-amazon-apigateway-integration responses      |\n\nSee the [EXAMPLES](https://github.com/yndlingsfar/serverless-openapi-integration-helper/tree/main/examples) directory for detailed instructions.\n\n# Auto Mock Generator\nIf enabled, the plugin generates mocking responses for all methods that do not have an x-amazon-apigateway-integration block defined.\nIt takes the first 2xx response defined in the openApi specification and generates a simple mocking response on the fly\n```yml\nopenApiIntegration:\n  autoMock: true\n  ...\n```\n\nWhen using the autoMock feature, you do not need to specify inputPath mappings, since all endpoints are mocked automatically\n\n```yml\nopenApiIntegration:\n    package: true\n    inputFile: schema.yml\n    mapping: ~\n```\n\n# VALIDATION generator\n\nThe plugin supports full request validation out of the box\n```yml\nopenApiIntegration:\n  validation: true\n  ...\n```\n\nIf enabled, the plugin generates the x-amazon-apigateway-request-validators blocks and adds a basic request validation to all methods.\nYou can customize the VALIDATION template by placing your own files inside a directory **openapi-integration** (in your project root). The following files can be overwritten:\n\n| Filename        | Description |\n| ------------- |:-------------:| \n| request-validator.yml    | The x-amazon-apigateway-request-validators block |\n\nSee the [EXAMPLES](https://github.com/yndlingsfar/serverless-openapi-integration-helper/tree/main/examples) directory for detailed instructions.\n\n# Proxy Manager\n\nThe proxymanager feature automates the complete generation of an HTTP proxy integration.\nYou only have to define the target URL and all necessary AWS integration blocks are generated on-the-fly during deployment.\n\n\n```yml\nopenApiIntegration:\n   cors: true\n   validation: true\n   mapping:\n      - stage: [dev, prod]\n        proxyManager:\n           type: http_proxy\n           baseUrl: https://www.example.com\n           pattern: \"(?\u003c=api\\/v1)\\/.+\"\n  ...\n```\n\n**With this setting, no separate integration files need to be created**\n\nA combination of your own and auto-generated files is still possible without any problems\n\n## Proxy Manager configuration\n### type\nat the moment only http_proxy supported\n\n### baseUrl\nThe base url is required to map the path variable from the openapi specification to the URI from the aws integration.\n\nExample:\n\n```yml\n#original openapi specification\npaths:\n   /api/v1/user:\n    post:\n      ... \n```\n\nwill be translated to\n\n```yml\n#generated openapi specification output\npaths:\n   /api/v1/user:\n      post:\n         ...\n         x-amazon-apigateway-integration:\n            type: http_proxy\n            passthroughBehavior: when_no_match\n            httpMethod: POST\n            uri: https://www.example.com/api/v1/user\n```\n\n### pattern\n\nThe pattern can be used to adapt the mapping of the base url using regexp, to remove a prefix, or a version string\n\nExample:\n\n```yml\nbaseUrl: https://www.example.com\npattern: \"(?\u003c=api\\/v1)\\/.+\"\n```\n\nwill translate the route **/api/v1/user** to https://www.example.com/user\n\n# Configuration Reference\n\nconfigure the plugin under the key **openApiIntegration**\n\n```yml\nopenApiIntegration:\n  inputFile: schema.yml #required\n  package: true #optional, defaults to false \n  inputDirectory: ./ #optional, defaults to ./\n  cors: true #optional, defaults to false\n  autoMock: true #optional, defaults to false\n  validation: true #optional, defaults to false\n  mapping: #optional, can be completely blank if autoMock option is enabled\n    - stage: [dev, prod] #multiple stages\n      path: integrations\n      proxyManager: #optional\n         type: http_proxy\n         baseUrl: https://example.com\n         pattern: \"(?\u003c=v1)\\/.+\"\n    - stage: test #single stage\n      path: mocks/customer.yml\n  outputFile: api.yml #optional, defaults to api.yml\n  outputDirectory: openapi-integration #optional, defaults to ./openapi-integration\n```\n\n# Known Issues\n\n## Stage deployment\nWhen using serverless framework only to deploy your aws resources **without having any lambda functions or triggers**, the AWS Gateway deploymemt does not behave as expected.\nAny deployment to an existing stage will be ignored, since CloudFormation does not redeploy a stage if the DeploymentIdentifier has not changed.\n\nThe plugin [serverless-random-gateway-deployment-id](https://www.npmjs.com/package/serverless-random-gateway-deployment-id) solves this problem by adding a random id to the deployment-name and all references to it on every deploy\n\nSee the **examples** folder for a full working [example](https://github.com/yndlingsfar/serverless-openapi-integration-helper/tree/main/examples)\n\n## Variable Resolving\nServerless variables inside the openapi integration files are not resolved correctly when using the package \u0026 deploy hooks. This problem can be solved by using the api gateway STAGE VARIABLES.\n\nSee the **examples** folder for a full working [example](https://github.com/yndlingsfar/serverless-openapi-integration-helper/tree/main/examples)\n\n# Example\n```yml\nservice:\n  name: user-registration\n\nprovider:\n  name: aws\n  stage: dev\n  region: eu-central-1\n\nplugins:\n  - serverless-openapi-integration-helper\n  \nopenApiIntegration:\n  inputFile: schema.yml\n  package: true\n  mapping:\n    - path: integrations\n      stage: [dev, prod]\n    - path: mocks/customer.yml\n      stage: test\n\nfunctions:\n\nresources:\n  Resources:\n    ApiGatewayRestApi:\n      Type: AWS::ApiGateway::RestApi\n      Properties:\n        ApiKeySourceType: HEADER\n        Body: ~\n        Description: \"Some Description\"\n        FailOnWarnings: false\n        Name: ${opt:stage, self:provider.stage}-some-name\n        EndpointConfiguration:\n          Types:\n            - REGIONAL\n    ApiGatewayDeployment:\n      Type: AWS::ApiGateway::Deployment\n      Properties:\n        RestApiId:\n          Ref: ApiGatewayRestApi\n        StageName: ${opt:stage, self:provider.stage}\n```\n\n```\nserverless deploy --stage=test\n```\n\n```\nserverless deploy --stage=prod\n```\n\n# Approach to a functional test of schema validation\nThe plugin works well in combination with the [serverless-plugin-test-helper](https://www.npmjs.com/package/serverless-plugin-test-helper) to automate tests against the deployed api gateway\n\n## Install The plugin test helper package\n\n```shell\nnpm install --save-dev serverless-plugin-test-helper\n```\n\nadd the plugin as a plugin dependency in your serverless configuration file and configure the plugin according to the [Readme](https://www.npmjs.com/package/serverless-plugin-test-helper)\n```yml\n#./serveless.yml\nplugins:\n  - serverless-plugin-test-helper\n  - serverless-openapi-integration-helper\n\n[...]\n\nresources:\n   Outputs:\n      GatewayUrl: # This is the key that will be used in the generated outputs file\n         Description: This is a helper for functional tests\n         Value: !Join\n            - ''\n            - - 'https://'\n              - !Ref ApiGatewayRestApi\n              - '.execute-api.'\n              - ${opt:region, self:provider.region}\n              - '.amazonaws.com/'\n              - ${opt:stage, self:provider.stage}\n\n   Resources:\n    ApiGatewayRestApi:\n      Type: AWS::ApiGateway::RestApi\n      Properties:\n        ApiKeySourceType: HEADER\n        Body: ~\n        Description: User Registration (${opt:stage, self:provider.stage})\n        FailOnWarnings: false\n        Name: ${opt:stage, self:provider.stage}-gateway\n        EndpointConfiguration:\n          Types:\n            - REGIONAL\n    ApiGatewayDeployment:\n      Type: AWS::ApiGateway::Deployment\n      Properties:\n        RestApiId:\n          Ref: ApiGatewayRestApi\n        StageName: ${opt:stage, self:provider.stage}\n```\n\n## Testing the schema validation\nAdd a functional test (e.g. with jest)\n\n```javascript\n//tests/registration.js\nimport {getOutput} from 'serverless-plugin-test-helper';\nimport axios from 'axios';\n\naxios.defaults.adapter = require('axios/lib/adapters/http'); //Todo\n\nconst URL = getOutput('GatewayUrl');\ntest('request validation on registration', async () =\u003e {\n    expect.assertions(1);\n    const {status} = await axios.post(URL + '/api/v1/user',\n        {\n            \"email_address\": \"test@example.com\",\n            \"password\": \"someStrongPassword#\"\n        },\n        {\n            headers: {\n                'Content-Type': 'application/json',\n            }\n        });\n    expect(status).toEqual(201);\n});\n\ntest('request validation on registration (invalid request)', async () =\u003e {\n    expect.assertions(1);\n    try {\n        await axios.post(URL + '/api/v1/user',\n            {\n                \"email\": \"test@example.com\"\n            },\n            {\n                headers: {\n                    'Content-Type': 'application/json',\n                }\n            });\n    } catch (e) {\n        expect(e.response).toMatchObject({\n            statusText: 'Bad Request',\n            status: 400\n        });\n    }\n});\n```\nThen perform the functional test\n```shell\nserverless deploy --stage=test\nnpm test\nserverless remove --stage=test\n```\n\nThe command will\n- merge the openapi specification file with the MOCK integration configured before\n- deploy to API Gateway in an isolated TEST infrastructure environment (your other environments will not be affected since we are deploying to a separated gateway)\n- perform the test and verify that schema validation is correct\n- remove all TEST resources if test succeeded\n\nSee the **examples** folder for a full working [example](https://github.com/yndlingsfar/serverless-openapi-integration-helper/tree/main/examples)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyndlingsfar%2Fserverless-openapi-integration-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyndlingsfar%2Fserverless-openapi-integration-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyndlingsfar%2Fserverless-openapi-integration-helper/lists"}