# @conqa/serverless-openapi-documentation 中文文档 规范地址：https://npmcn.com/package/%40conqa/serverless-openapi-documentation/ 版本：2\.0\.0 npm 元数据更新时间：2026-10-11T16:48:54.518Z 中文译文更新时间：2026-11-10T15:49:24.681Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40conqa/serverless-openapi-documentation 原文对照：https://npmcn.com/package/%40conqa/serverless-openapi-documentation/?lang=original 项目主页：https://github.com/conqa/serverless-openapi-documentation#readme 源码仓库：https://github.com/conqa/serverless-openapi-documentation 弃用说明：This package is UNMAINTAINED ## 关键信息（来自 npm 元数据） - 包体积（解压后）：523 kB，47 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - Node.js 要求：\>=10\.0\.0 - 运行依赖：8 个 - 首次发布：2019-05-02T04:11:04.648Z - 最新版本发布：2021-12-09T21:03:17.595Z - 近 30 天下载量：152705（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：7（近 12 个月 0 个） ## 中文简介 从无服务器配置生成 OpenAPI V3 文档的无服务器 1.0 插件 ## 安装 ```sh npm install @conqa/serverless-openapi-documentation ``` 也可以使用：`pnpm add @conqa/serverless-openapi-documentation`、`yarn add @conqa/serverless-openapi-documentation`、`bun add @conqa/serverless-openapi-documentation` ## README # 这个PLUGIN是没有包含 请注意, 此插件没有维护, 虽然您可以使用由此生成的插件, 但它不会以任何方式更新 . 问题和公关不予审查或接受。 如果此插件对您有用, 请随意使用叉并继续使用, 它目前未被原维护者使用 . # 无服务器的 OpenAPI 文档插件 [![NPM](https://img.shields.io/npm/v/@conqa/serverless-openapi-documentation.svg)](https://npmjs.org/packages/@conqa/serverless-openapi-documentation/) [![Travis CI](https://img.shields.io/travis/conqa/serverless-openapi-documentation.svg)](https://travis-ci.org/conqa/serverless-openapi-documentation) 生成 [**OpenAPI 3. 0**](https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md) 无服务器配置文件的文档。 OpenAPI原名斯瓦格. 配置受下列格式的启发: [无服务器锯入文档](https://www.npmjs.com/package/serverless-aws-documentation)。 。 。 . 不错 [ReDoc 数据](https://github.com/Rebilly/ReDoc)。 。 。 . * * * - [使用量](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-usage) - [选项](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-options) - [配置](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-configuration) - [模型](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-models) - [职能](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-functions) - [`queryParams`](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-queryparams) - [`pathParams`](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-pathparams) - [`cookieParams`](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-cookieparams) - [`requestModels`](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-requestmodels) - [`methodResponses`](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-methodresponses) - [示例配置](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-example-configuration) - [安装](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-install) * * * ## 使用量 此插件需要额外的配置来使用, 参见 "[配置](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-configuration)" 如何配置生成文档的插件的一节. 以下是运行生成器的命令行选项: ```bash serverless openapi generate [options] ``` ### 选项 ```bash Plugin: ServerlessOpenAPIDocumentation openapi generate ...................... Generate OpenAPI v3 Documentation --output / -o ...................... Output file location [default: openapi.yml|json] --format / -f ...................... OpenAPI file format (yml|json) [default: yml] --indent / -i ...................... File indentation in spaces [default: 2] --help / -h ...................... Help ``` ### 配置 要配置此插件以生成有效的 OpenAPI 文档, 您需要修改两个位置 `serverless.yml` 文档中 `custom` 变量节和 `http` 用于您服务中每个指定函数的事件区域. 此插件兼容同样的文档配置结构 [无服务器锯入文档](https://www.npmjs.com/package/serverless-aws-documentation) 并可以跑在旁边. 这个 `custom` 区域 `serverless.yml` 可配置如下: ```yml custom: documentation: version: '1' title: 'My API' description: 'This is my API' # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject securitySchemes: {} # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#security-requirement-object security: {} models: {} ``` 这些配置可以相当动词;你可以将其分离成自己的文件,例如: `serverless.doc.yml` 现改为: ```yml custom: documentation: ${file(serverless.doc.yml):documentation} functions: myFunc: events: - http: path: getStuff method: get documentation: ${file(serverless.doc.yml):endpoints.myFunc} ``` 关于更多信息 `serverless.yml` 语法,参见他们的道克. #### 模型 模型包含额外信息,可以用来定义端点的策略. 您必须定义 _内容类型_ 您在模型中提供的每个方案. 这个 _所需经费_ 示范部分的指令如下: - `name`: schema的名称 - `description`:说明计划 - `contentType`: 所描述的请求/答复的内容类型(e. `application/json` 或者说 `application/xml`) (中文(简体) ). - `schema`:"JSON·斯克马"(JSON Schema)[网站](http://json-schema.org/)),描述了模型. 你们也可以: - 使用内线 `YAML` 定义这些 - 使用无服务器的功能合并到外部 schema 文件 - 指定 json schema 的路径,在这种情况下, 如果您在多个 schemas 中重复使用某些类型 - 它们在生成的组件中将包含一次, 而不是重复每个 引用 schema ```yml custom: documentation: models: - name: "PutDocumentRequest" description: "Inline schema example" contentType: "application/json" schema: $schema: "http://json-schema.org/draft-04/schema#" properties: SomeObject: type: "object" properties: SomeAttribute: type: "string" - name: "PutDocumentResponse" description: "External file merge example" contentType: "application/json" schema: ${file(models/PutDocumentResponse.json)} - name: "ErrorResponse" description: "Path to a schema example" contentType: "application/json" schema: models/ErrorResponse.json ``` #### 职能 要定义给定函数事件的文档, 您需要创建 `documentation` 在您的 http 事件属性 `serverless.yml` 文档. 这个 `documentation` 事件配置的章节可以包含以下属性: - `summary`:对该方法的简短描述 - `description`:方法的详细说明 - `tags`: 此事件的标记数组 - `deprecated`: 显示客户端应当移出此功能的布尔指标 - `requestBody`: 包含对请求的说明 - `description`: 对请求机构的描述 - `requestModels`: 描述请求机构的模型清单(见 [请求模式](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-requestmodels) (见下文) - `queryParams`: 查询参数列表(参见 [查询](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-queryparams) (见下文) - `pathParams`: 路径参数列表(参见 [路径](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-pathparams) (见下文) - `cookieParams`: cookie 参数列表(参见 [饼干](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-cookieparams) (见下文) - `methodResponses`: 一系列反应模式和适用状态代码 - `statusCode`: 适用的http状态代码(例如200/404/500等) - `responseBody`: 载有答复说明 - `description`: 身体反应说明 - `responseHeaders`: 反应头列表(参见 [响应页眉](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-responseheaders) (见下文) - `responseModels`: 描述请求机构的模型清单(见 [响应模式](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-responsemodels) (见下文) `Content-Type` ```yml functions: createUser: handler: "handler.create" events: - http: path: "create" method: "post" documentation: summary: "Create User" description: "Creates a user and then sends a generated password email" requestBody: description: "A user information object" requestModels: application/json: "PutDocumentRequest" pathParams: - name: "username" description: "The username for a user to create" schema: type: "string" pattern: "^[-a-z0-9_]+$" queryParams: - name: "membershipType" description: "The user's Membership Type" schema: type: "string" enum: - "premium" - "standard" cookieParams: - name: "SessionId" description: "A Session ID variable" schema: type: "string" methodResponses: - statusCode: 201 responseBody: description: "A user object along with generated API Keys" responseModels: application/json: "PutDocumentResponse" - statusCode: 500 responseBody: description: "An error message when creating a new user" responseModels: application/json: "ErrorResponse" ``` #### `queryParams` 查询参数如下: - `name`: 查询变量的名称 - `description`: 查询变量描述 - `required`: 查询参数是否为强制(布尔) - `schema`: JSON schema( 内含或文件) ```yml queryParams: - name: "filter" description: "The filter parameter" required: true schema: type: "string" ``` #### `pathParams` 路径参数可描述如下: - `name`: 查询变量的名称 - `description`: 查询变量描述 - `schema`: JSON schema( 内含或文件) ```yml pathParams: - name: "usernameId" description: "The usernameId parameter" schema: type: "string" ``` #### `cookieParams` Cookie 参数可描述如下: - `name`: 查询变量的名称 - `description`: 查询变量描述 - `required`: 查询参数是否为强制(布尔) - `schema`: JSON schema( 内含或文件) ```yml cookieParams: - name: "sessionId" description: "The sessionId parameter" required: true schema: type: "string" ``` #### `requestModels` 这个 `requestModels` 属性允许您定义函数事件 HTTP 请求的模型。 您可以定义每个不同的模型 `Content-Type`。您可以定义在 `models` 区域 [定义模式](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-models) 页:1. ```yml requestModels: application/json: "CreateRequest" application/xml: "CreateRequestXML" ``` #### `methodResponses` 您可以通过定义函数事件的属性来定义响应策略 . 举例来说 `methodResponses` 事件配置如下: ```yml methodResponse: - statusCode: 200 responseHeaders: - name: "Content-Type" description: "Content Type header" schema: type: "string" responseModels: application/json: "CreateResponse" application/xml: "CreateResponseXML" ``` ##### `responseModels` 这个 `responseModels` 属性允许您定义函数事件 HTTP 响应的模型。 您可以定义每个不同的模型 `Content-Type`中定义的响应模式 `models` 区域 [定义模式](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/#readme-models) 页:1. ```yml responseModels: application/json: "CreateResponse" application/xml: "CreateResponseXML" ``` ##### `responseHeaders` 财务报告和审定财务报表 `requestHeaders` 这个 `responseHeaders/requestHeaders` 区域配置允许您为函数事件定义 HTTP 标题. 信头的属性如下: - `name`: HTTP 页眉的名称 - `description`: HTTP 信头的描述 - `schema`: JSON schema( 内含或文件) ```yml responseHeaders: - name: "Content-Type" description: "Content Type header" schema: type: "string" requestHeaders: - name: "Content-Type" description: "Content Type header" schema: type: "string" ``` ## 示例配置 请查看此示例 [无服务器. yml](https://npmcn.com/package/%40conqa/serverless-openapi-documentation/test/project/serverless.yml)。 。 。 . ## 安装 此插件适用于无服务器 1. x并上 。 无服务器 0. 5 不支持 . 要将此插件添加到您的软件包中。 json : **使用 npm :** ```bash npm install @conqa/serverless-openapi-documentation --save-dev ``` **使用 Yarn :** ```bash yarn add @conqa/serverless-openapi-documentation --dev ``` 您接下来需要将插件添加到 `plugins` 区域 `serverless.yml` 文档. ```yml plugins: - @conqa/serverless-openapi-documentation ``` 您可以通过运行确认插件安装正确 : ```bash serverless | grep -i "ServerlessOpenAPIDocumentation" ``` 它应该回来了 `ServerlessOpenAPIDocumentation` 作为列表中的插件之一. > 注意: 添加此插件 _之后_ `serverless-offline` 防止出现问题 `String.replaceAll` 被错误地推翻. ## 许可证 麻省理工学院 ## 常见问题 ### @conqa/serverless-openapi-documentation 是什么？ 从无服务器配置生成 OpenAPI V3 文档的无服务器 1\.0 插件注意：该包已被作者标记为弃用——This package is UNMAINTAINED ### 如何安装 @conqa/serverless-openapi-documentation？ 在项目目录运行 npm install @conqa/serverless-openapi-documentation，或使用 pnpm add / yarn add / bun add。 ### @conqa/serverless-openapi-documentation 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/conqa\_\_serverless-openapi-documentation 是否存在。 ### @conqa/serverless-openapi-documentation 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @conqa/serverless-openapi-documentation 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=10\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @conqa/serverless-openapi-documentation 可以商用吗？ @conqa/serverless-openapi-documentation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @conqa/serverless-openapi-documentation 的下载量有多少？ 根据 npm 官方下载统计，@conqa/serverless-openapi-documentation 在 2026/10/11 – 2026/11/09 这 30 天内被下载 152,705 次，日均约 5,090 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @conqa/serverless-openapi-documentation 还在维护吗？ 最新版本 2\.0\.0 发布于 2021/12/10（4 年前）；至今共发布 7 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/05/02。作者已将其标记为弃用，新项目建议寻找替代方案。