{"id":25356463,"url":"https://github.com/env0/serverless-openapi-typescript","last_synced_at":"2025-09-23T23:17:52.042Z","repository":{"id":38340195,"uuid":"400071702","full_name":"env0/serverless-openapi-typescript","owner":"env0","description":"Serverless plugin to generate OpenAPI 3.1.0 documentation including models from serverless configuration and TypeScript","archived":false,"fork":false,"pushed_at":"2024-05-27T12:03:39.000Z","size":266,"stargazers_count":14,"open_issues_count":18,"forks_count":7,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-09-15T10:56:48.397Z","etag":null,"topics":["json-schema","openapi","openapi3","openapi3-1","serverless","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/env0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-08-26T06:57:36.000Z","updated_at":"2024-05-27T12:03:43.000Z","dependencies_parsed_at":"2024-06-21T16:43:48.564Z","dependency_job_id":"fbe5a849-5560-46b0-8d62-11f8eebaa652","html_url":"https://github.com/env0/serverless-openapi-typescript","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/env0/serverless-openapi-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/env0%2Fserverless-openapi-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/env0%2Fserverless-openapi-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/env0%2Fserverless-openapi-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/env0%2Fserverless-openapi-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/env0","download_url":"https://codeload.github.com/env0/serverless-openapi-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/env0%2Fserverless-openapi-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276662987,"owners_count":25682185,"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","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["json-schema","openapi","openapi3","openapi3-1","serverless","typescript"],"created_at":"2025-02-14T20:47:07.281Z","updated_at":"2025-09-23T23:17:52.006Z","avatar_url":"https://github.com/env0.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless OpenAPI TypeScript Plugin\n\nGenerates [**OpenAPI 3.1.0**](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.1.0.md) documentation from serverless configuration files **including fully generated request/response models from TypeScript**.  \n\nThis is an extension plugin to the most excellent [@conqa/serverless-openapi-documentation](https://www.npmjs.com/package/@conqa/serverless-openapi-documentation).  \n\nPartilly works with [ReDoc](https://github.com/Rebilly/ReDoc) as they're still working on OpenAPI 3.1.0 support.  \nWorks well with [Stoplight.io](https://stoplight.io/)    \n\n\u003e **Why OpenAPI 3.1.0 and not 3.0.0?**  \n\u003e Because types generated from TypeScript are complex and require at least json-schema draft07 to be described properly.  \n\u003e OpenAPI 3.1.0 is the first version to be fully compatible with JSON Schema - 3.0.0 is just an \"extended subset\" of draft05\n\n---\n\n- [Usage](#usage)\n    - [Options](#options)\n    - [Configuration](#configuration)\n        - [Models](#models)\n        - [Functions](#functions)\n        - [`queryParams`](#queryparams)\n        - [`pathParams`](#pathparams)\n        - [`cookieParams`](#cookieparams)\n        - [`requestModels`](#requestmodels)\n        - [`methodResponses`](#methodresponses-and-responsemodels)\n        - [`webhooks`](#webhooks)\n- [Install](#install)\n\n---\n\n## Usage\n\nThis plugin requires additional configuration to use, see the \"[Configuration](#configuration)\" section for how to configure the plugin to generate documentation.\n\nBelow are the commandline options to run the generator:\n\n```bash\nserverless openapi generate [options]\n```\n\n### Options\n\n```bash\nPlugin: ServerlessOpenAPIDocumentation\nopenapi generate  ...................... Generate OpenAPI v3 Documentation\n    --output / -o ...................... Output file location [default: openapi.yml|json]\n    --format / -f ...................... OpenAPI file format (yml|json) [default: yml]\n    --indent / -i ...................... File indentation in spaces [default: 2]\n    --help / -h   ...................... Help\n```\n\n### Configuration\n\nTo configure this plugin to generate valid OpenAPI documentation there are two places you'll need to modify in your `serverless.yml` file, the `custom` variables section and the `http` event section for each given function in your service.\n\nThis plugin is compatible with the same documentation configuration structure in [@conqa/serverless-openapi-documentation](https://www.npmjs.com/package/@conqa/serverless-openapi-documentation) and needs to be run beside it.\n\nThe `custom` section of your `serverless.yml` can be configured as below:\n\n```yml\ncustom:\n  documentation:\n    version: '1'\n    title: 'My API'\n    description: 'This is my API'\n    # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject\n    securitySchemes: {}\n    # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#security-requirement-object\n    security: {}\n    models: {}\n    typescriptApiPath: 'api.d.ts'\n    tsconfigPath: 'tsconfig.json'\n```\n\nThese configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:\n\n```yml\ncustom:\n  documentation: ${file(serverless.doc.yml):documentation}\n\nfunctions:\n  myFunc:\n    events:\n      - http:\n          path: getStuff\n          method: get\n          documentation: ${file(serverless.doc.yml):endpoints.myFunc}\n```\n\nFor more info on `serverless.yml` syntax, see their docs.\n\n#### Models\n\nThese will be generated for you from TypeScript.  \nFor information on how to specify these yourself, see [Models](https://github.com/conqa/serverless-openapi-documentation#models) on the base plugin page.    \n\n#### Functions\n\nTo define the documentation for a given function event, you need to create a `documentation` attribute for your http event in your `serverless.yml` file.  \n\nThis plugin will assert the `documentation` attribute is set on every non `private: true` function with an `http` event.  \n\nIf you wish a function to not be listed on your documentation, you must explicitly set `documentation: ~` to disable docs on that function.    \n\nThe `documentation` section of the event configuration can contain the following attributes:\n\n* `summary`: a short description of the method\n* `description`: a detailed description of the method\n* `tags`: an array of tags for this event\n* `deprecated`: boolean indicator that indicates clients should migrate away from this function\n* `requestBody`: contains description of the request\n    * `description`: a description of the request body\n* `requestModels`: a list of models to describe the request bodies (see [requestModels](#requestmodels) below) - **these will be autogenerated for you from TypeScript**\n* `queryParams`: a list of query parameters (see [queryParams](#queryparams) below) - **these _can_ be autogenerated for you from TypeScript**\n* `pathParams`: a list of path parameters (see [pathParams](#pathparams) below) - **these _can_ be autogenerated for you from TypeScript**\n* `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieparams) below)\n* `methodResponses`: an array of response models and applicable status codes (see [methodResponses](#methodresponses-and-responsemodels)) - **these _will_ be autogenerated for you from TypeScript**\n* `webhooks`: an object with all the webhooks with descriptions (see [webhooks](#webhooks)) - **these _will_ be autogenerated for you from TypeScript**\n\n```yml\nfunctions:\n  createUser:\n    handler: \"handler.create\"\n    events:\n      - http:\n        path: \"create\"\n        method: \"post\"\n        documentation:\n          summary: \"Create User\"\n          description: \"Creates a user and then sends a generated password email\"\n          requestBody:\n            description: \"A user information object\"\n          requestModels:\n            application/json: \"PutDocumentRequest\"\n          pathParams:\n            - name: \"username\"\n              description: \"The username for a user to create\"\n              schema:\n                type: \"string\"\n                pattern: \"^[-a-z0-9_]+$\"\n          queryParams:\n            - name: \"membershipType\"\n              description: \"The user's Membership Type\"\n              schema:\n                type: \"string\"\n                enum:\n                  - \"premium\"\n                  - \"standard\"\n          cookieParams:\n            - name: \"SessionId\"\n              description: \"A Session ID variable\"\n              schema:\n                type: \"string\"\n          methodResponses:\n            - statusCode: 201\n              responseBody:\n                description: \"A user object along with generated API Keys\"\n              responseModels:\n                application/json: \"PutDocumentResponse\"\n            - statusCode: 500\n              responseBody:\n                description: \"An error message when creating a new user\"\n              responseModels:\n                application/json: \"ErrorResponse\"\n```\n\n#### `queryParams`\n\nQuery parameters can be described as follow:\n\n* `name`: the name of the query variable\n* `description`: a description of the query variable\n* `required`: whether the query parameter is mandatory (boolean)\n* `schema`: JSON schema (inline or file) **or a string representing fully qualified TypeScript type to generate schema from**\n\n\u003e Note: If schema is not specified one will be autogenerated for you as `{ \"type\": \"string\" }` if you specify `querystrings` in your [Serverless request parameters](https://www.serverless.com/framework/docs/providers/aws/events/apigateway#request-parameters)\n\n##### Explicit schema example\n```yml\nqueryParams:\n  - name: \"filter\"\n    description: \"The filter parameter\"\n    required: true\n    schema:\n      type: \"string\"\n```\n\n##### Autogenerated Schema from Serverless config\n```yml\nfunctions:\n  foo:\n    events:\n      - http:\n          request:\n            parameters:\n              querystrings:\n                filter: true\n\n# This will be autogenerated for you based on your Serverless config above! No need to write it yourself:                \n# queryParams:\n#  - name: \"filter\"\n#    required: true \n#    schema:\n#      type: \"string\"\n```\n\n##### Generated Schema from TypeScript type\n```typescript\nexport namespace MyApi {\n    export namespace FooBar {\n        export namespace Request {\n            export namespace QueryParams {\n                // You may use JSdoc to set JSON Schema attributes! \n                /** @description The filter parameter **/\n                export type Filter = 'hello' | 'world';\n            }\n        }\n    }\n}\n```\n\n```yml\nfunctions:\n  fooBar:\n    events:\n      - http:\n          documentation:\n            queryParams:\n              - name: \"filter\"\n                schema: \"MyApi.FooBar.Request.QueryParams.Filter\"\n          request:\n            parameters:\n              querystrings:\n                filter: false\n\n# This will be autogenerated for you based from TypeScript! No need to write it yourself                \n# queryParams:\n#  - name: \"filter\"\n#    required: false\n#    description: \"The filter parameter\"  \n#    schema:\n#      type: string\n#      enum:\n#        - hello\n#        - world\n```\n\n#### `pathParams`\n\nPath parameters can be described as follow:\n\n* `name`: the name of the query variable\n* `description`: a description of the query variable\n* `schema`: JSON schema (inline or file) **or a string representing fully qualified TypeScript type to generate schema from**\n\n##### Explicit schema example\n\n```yml\npathParams:\n  - name: \"usernameId\"\n    description: \"The usernameId parameter\"\n    schema:\n      type: \"string\"\n```\n\n##### Autogenerated Schema from Serverless config\n```yml\nfunctions:\n  foo:\n    events:\n      - http:\n          request:\n            parameters:\n              pahts:\n                usernameId: true\n\n# This will be autogenerated for you based on your Serverless config above! No need to write it yourself:                \n# queryParams:\n#  - name: \"filter\"\n#    required: true \n#    schema:\n#      type: \"string\"\n```\n\n##### Generated Schema from TypeScript type\n```typescript\nexport namespace MyApi {\n    export namespace FooBar {\n        export namespace Request {\n            export namespace PathParams {\n                // You may use JSdoc to set JSON Schema attributes! \n                /** @description The usernameId parameter **/\n                export type UsernameId = string;\n            }\n        }\n    }\n}\n```\n\n```yml\nfunctions:\n  fooBar:\n    events:\n      - http:\n          documentation:\n            paths:\n              - name: \"usernameId\"\n                schema: \"MyApi.FooBar.Request.QueryParams.Filter\"\n          request:\n            parameters:\n              paths:\n                usernameId: true\n\n# This will be autogenerated for you based from TypeScript! No need to write it yourself                \n# queryParams:\n#  - name: \"filter\"\n#    required: true \n#    description: \"The usernameId parameter\"\n#    schema:\n#      type: string\n```\n\n#### `cookieParams`\n\nTypeScript generation for these isn't supported.  \nFor information on how to specify these yourself, see [Cookie Parameters](https://github.com/conqa/serverless-openapi-documentation#cookieparams) on the base plugin page.\n\n#### `requestModels`\n\nThe `requestModels` property allows you to define models for the HTTP Request of the function event.  \n\nThese will be autogenerated for you from TypeScript **by convention**.  \nThe plugin will autogenerate a request model for every `put`, `patch` or `post` method based on the TypeScript type found by convention.    \nThe look strategy will be by:  \n`${serverless.custom.documentation.apiNamespace}.${upper-case-name-of-function}.Request.Body`. Note that any underscores (`_`) or hyphens (`-`) in function names will be excluded in the resolved type (e.g. the Serverless function `my_get-function` will resolve to `MyGetFunction` in Typescript)  \n\nFor example, the following function:  \n```yaml\nfunctions:\n  myFunction: \n    events:\n      - http:\n        documentation:\n          summary: \"Does a lot for you\"\n```\n\nWill look for the resolve type as its request model:  \n```typescript\n// api.d.ts\n\nexport namespace MyApi {\n    export namespace MyFunction {\n        export namespace Request {\n            export type Body = {\n                id: string,\n                name: string,\n                age: number\n                // ...\n            }\n        }\n    }\n}\n```\n\n#### `methodResponses` and `responseModels`\n\nThese will be autogenerated for you from TypeScript **by convention**.  \nThe plugin will autogenerate a response model for every `put`, `patch`, `post` and `get` method based on the TypeScript type found by convention.  \nThe response will use the generated type as body, and will have a 200 status code.  \n`delete` method will be generated with an empty body and 204 status code.  \nOnly `application/json` response types are supported.  \n\nThe look strategy will be by:  \n`${serverless.custom.documentation.apiNamespace}.${upper-case-name-of-function}.Response`\n\nFor example, the following function:\n```yaml\nfunctions:\n  myFunction: \n    events:\n      - http:\n        documentation:\n          summary: \"Does a lot for you\"\n```\n\nWill look for the resolve type as its request model:\n```typescript\n// api.d.ts\n\nexport namespace MyApi {\n  export namespace MyFunction {\n    export type Response = {\n      id: string,\n      name: string,\n      age: number\n      // ...\n    }\n  }\n}\n```\n\n##### `responseHeaders` and `requestHeaders`\n\nThe `responseHeaders/requestHeaders` section of the configuration allows you to define the HTTP headers for the function event.    \nTypeScript generation for these isn't supported.    \nFor information on how to specify these yourself, see [Response Headers](https://github.com/conqa/serverless-openapi-documentation#responseheaders-and-requestheaders) on the base plugin page.  \n\n##### `customTags`\n\nIn some cases where a single serverless.yml contains endpoints which can be grouped differently,\nyou can define custom tags as following:\n\n```yaml\ncustom:\n  documentation:\n    title: 'Project'\n    description: DummyDescription\n\n    apiNamespace: ProjectApi\n    tags:\n       - name: FooBarTitle\n         description: FooBarDescription\n       - name: BazTitle\n         description: BazDescription\n```\n\n```yaml\nfunctions:\n  createFunc:\n    handler: handler.create\n    events:\n      - http:\n          documentation:\n            summary: \"Create Function\"\n            tag: FooBarTitle\n```\n\nEndpoints that are not attached to a custom tag, are still attached to the title ( which is the default tag ).\n\n#### `webhooks`\nOpenAPI have an option to add your application `webhooks`, while this feature isn't supported by `serverless`.\n\nFor those the plugin will look for the webhooks under `custom.documentation.webhooks`.\n\nFor example\n\n```yaml\ncustom:\n  documentation:\n    apiNamespace: MyApi\n    webhooks:\n      WebhookName:\n        post:\n          requestBody:\n            description: |\n              This is a request body description\n          responses:\n            200:\n              description: |\n                This is a expected response description\n```\n\nthis will generate the next OpenAPI file\n\n```yaml\ncomponents:\n  schemas:\n    MyApi.Webhooks.WebhookName:\n      type: object\nwebhooks:\n  WebhookName:\n    post:\n      requestBody:\n        description: |\n          This is a request body description\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/MyApi.Webhooks.WebhookName'\n      responses:\n        '200':\n          description: |\n            This is a expected response description\n```\n\nWith the next `api.d.ts`:\n\n```typescript\nexport namespace MyApi {\n  export namespace Webhooks {\n    export type WebhookName = {\n      id: string,\n      name: string,\n      age: number\n      // ...\n    }\n  }\n}\n```\n\nYou can also add Webhook tags by using `webhookTags` keyword it will auto add tag to all webhooks\n```yaml\ncustom:\n  documentation:\n    apiNamespace: MyApi\n    webhookTags:\n      - name: ProjectWebhooks\n        description: This is the description for ProjectWebhooks\n    webhooks:\n      WebhookName:\n        post:\n          requestBody:\n            description: |\n              This is a request body description\n          responses:\n            200:\n              description: |\n                This is a expected response description\n```\n\n\n## Install\n\nThis plugin is **an extension**.  \nIt means you must install and enable `@conqa/serverless-openapi-documentation` too.\n\nTo add these plugins to your package.json:\n\n**Using npm:**\n```bash\nnpm install @conqa/serverless-openapi-documentation --save-dev\nnpm install serverless-openapi-typescript --save-dev\n```\n\n**Using Yarn:**\n```bash\nyarn add @conqa/serverless-openapi-documentation --dev\nyarn add serverless-openapi-typescript --dev\n```\n\nNext you need to add the plugin to the `plugins` section of your `serverless.yml` file.\n\n```yml\nplugins:\n  - @conqa/serverless-openapi-documentation\n  - serverless-openapi-typescript\n  # NOTE: Order is important here - this plugin must be added after the base @conqa/serverless-openapi-documentation plugin\n  # This plugin asserts that - you will get a validation message if you get the ordering wrong \n```\n\n\u003e Note: Add this plugin _after_ `serverless-offline` to prevent issues with `String.replaceAll` being overridden incorrectly.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenv0%2Fserverless-openapi-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenv0%2Fserverless-openapi-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenv0%2Fserverless-openapi-typescript/lists"}