{"id":18667757,"url":"https://github.com/temando/serverless-openapi-documentation","last_synced_at":"2025-04-05T00:07:17.960Z","repository":{"id":38551584,"uuid":"96071001","full_name":"temando/serverless-openapi-documentation","owner":"temando","description":"Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration","archived":false,"fork":false,"pushed_at":"2023-12-05T17:31:40.000Z","size":155,"stargazers_count":92,"open_issues_count":25,"forks_count":126,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-06-11T17:41:16.012Z","etag":null,"topics":["open-api-v3","openapi","openapi-documentation","serverless"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/temando.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":"2017-07-03T04:44:51.000Z","updated_at":"2024-06-18T15:33:08.616Z","dependencies_parsed_at":"2024-06-18T15:42:54.418Z","dependency_job_id":null,"html_url":"https://github.com/temando/serverless-openapi-documentation","commit_stats":{"total_commits":73,"total_committers":9,"mean_commits":8.11111111111111,"dds":"0.31506849315068497","last_synced_commit":"6df0be3f6eb30cc4fa00241e91c33a2acae2df28"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temando%2Fserverless-openapi-documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temando%2Fserverless-openapi-documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temando%2Fserverless-openapi-documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temando%2Fserverless-openapi-documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/temando","download_url":"https://codeload.github.com/temando/serverless-openapi-documentation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"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":["open-api-v3","openapi","openapi-documentation","serverless"],"created_at":"2024-11-07T08:39:57.150Z","updated_at":"2025-04-05T00:07:17.939Z","avatar_url":"https://github.com/temando.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless OpenAPI Documentation Plugin\n\n[![NPM](https://img.shields.io/npm/v/serverless-openapi-documentation.svg)](https://npmjs.org/packages/serverless-openapi-documentation/)\n[![Travis CI](https://img.shields.io/travis/temando/serverless-openapi-documentation.svg)](https://travis-ci.org/temando/serverless-openapi-documentation)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\nGenerates [**OpenAPI 3.0.0**](https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md) documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is inspired by the format used in [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation).\n\nWorks well with [Lincoln OpenAPI Renderer](https://github.com/temando/open-api-renderer).\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)\n- [Example Configuration](#example-configuration)\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 [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation) and can 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    models: {}\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\nModels contain additional information that you can use to define schemas for endpoints.  You must define the *content type* for each schema that you provide in the models.\n\nThe *required* directives for the models section are as follow:\n\n* `name`: the name of the schema\n* `description`: a description of the schema\n* `contentType`: the content type of the described request/response (ie. `application/json` or `application/xml`).\n* `schema`: The JSON Schema ([website](http://json-schema.org/)) that describes the model. You can either use inline `YAML` to define these, or refer to an external schema file as below\n\n```yml\ncustom:\n  documentation:\n    models:\n      - name: \"ErrorResponse\"\n        description: \"This is an error\"\n        contentType: \"application/json\"\n        schema: ${file(models/ErrorResponse.json)}\n      - name: \"PutDocumentResponse\"\n        description: \"PUT Document response model (external reference example)\"\n        contentType: \"application/json\"\n        schema: ${file(models/PutDocumentResponse.json)}\n      - name: \"PutDocumentRequest\"\n        description: \"PUT Document request model (inline example)\"\n        contentType: \"application/json\"\n        schema:\n          $schema: \"http://json-schema.org/draft-04/schema#\"\n          properties:\n            SomeObject:\n              type: \"object\"\n              properties:\n                SomeAttribute:\n                  type: \"string\"\n```\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\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)\n* `queryParams`: a list of query parameters (see [queryParams](#queryparams) below)\n* `pathParams`: a list of path parameters (see [pathParams](#pathparams) below)\n* `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieparams) below)\n* `methodResponses`: an array of response models and applicable status codes\n  * `statusCode`: applicable http status code (ie. 200/404/500 etc.)\n  * `responseBody`: contains description of the response\n    * `description`: a description of the body response\n  * `responseHeaders`: a list of response headers (see [responseHeaders](#responseheaders) below)\n  * `responseModels`: a list of models to describe the request bodies (see [responseModels](#responsemodels) below) for each `Content-Type`\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)\n\n```yml\nqueryParams:\n  - name: \"filter\"\n    description: \"The filter parameter\"\n    required: true\n    schema:\n      type: \"string\"\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)\n\n```yml\npathParams:\n  - name: \"usernameId\"\n    description: \"The usernameId parameter\"\n    schema:\n      type: \"string\"\n```\n\n#### `cookieParams`\n\nCookie 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)\n\n```yml\ncookieParams:\n  - name: \"sessionId\"\n    description: \"The sessionId parameter\"\n    required: true\n    schema:\n      type: \"string\"\n```\n\n#### `requestModels`\n\nThe `requestModels` property allows you to define models for the HTTP Request of the function event. You can define a different model for each different `Content-Type`. You can define a reference to the relevant request model named in the `models` section of your configuration (see [Defining Models](#models) section).\n\n```yml\nrequestModels:\n  application/json: \"CreateRequest\"\n  application/xml: \"CreateRequestXML\"\n```\n\n#### `methodResponses`\n\nYou can define the response schemas by defining properties for your function event.\n\nFor an example of a `methodResponses` configuration for an event see below:\n\n```yml\nmethodResponse:\n  - statusCode: 200\n    responseHeaders:\n      - name: \"Content-Type\"\n        description: \"Content Type header\"\n        schema:\n          type: \"string\"\n    responseModels:\n      application/json: \"CreateResponse\"\n      application/xml: \"CreateResponseXML\"\n```\n\n##### `responseModels`\n\nThe `responseModels` property allows you to define models for the HTTP Response of the function event. You can define a different model for each different `Content-Type`. You can define a reference to the relevant response model named in the `models` section of your configuration (see [Defining Models](#models) section).\n\n```yml\nresponseModels:\n  application/json: \"CreateResponse\"\n  application/xml: \"CreateResponseXML\"\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.\n\nThe attributes for a header are as follow:\n\n* `name`: the name of the HTTP Header\n* `description`: a description of the HTTP Header\n* `schema`: JSON schema (inline or file)\n\n```yml\nresponseHeaders:\n  - name: \"Content-Type\"\n    description: \"Content Type header\"\n    schema:\n      type: \"string\"\nrequestHeaders:\n  - name: \"Content-Type\"\n    description: \"Content Type header\"\n    schema:\n      type: \"string\"\n```\n\n## Example configuration\n\nPlease view the example [serverless.yml](test/project/serverless.yml).\n\n## Install\n\nThis plugin works for Serverless 1.x and up. Serverless 0.5 is not supported.\n\nTo add this plugin to your package.json:\n\n**Using npm:**\n```bash\nnpm install serverless-openapi-documentation --save-dev\n```\n\n**Using Yarn:**\n```bash\nyarn add serverless-openapi-documentation --dev\n```\n\nNext you need to add the plugin to the `plugins` section of your `serverless.yml` file.\n\n```yml\nplugins:\n  - serverless-openapi-documentation\n```\n\nYou can confirm the plugin is correctly installed by running:\n\n```bash\nserverless | grep -i \"ServerlessOpenAPIDocumentation\"\n```\n\nIt should return `ServerlessOpenAPIDocumentation` as one of the plugins on the list.\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%2Ftemando%2Fserverless-openapi-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftemando%2Fserverless-openapi-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemando%2Fserverless-openapi-documentation/lists"}