这个PLUGIN是没有包含
请注意, 此插件没有维护, 虽然您可以使用由此生成的插件, 但它不会以任何方式更新 .
问题和公关不予审查或接受。 如果此插件对您有用, 请随意使用叉并继续使用, 它目前未被原维护者使用 .
无服务器的 OpenAPI 文档插件
生成 OpenAPI 3. 0 无服务器配置文件的文档。 OpenAPI原名斯瓦格. 配置受下列格式的启发: 无服务器锯入文档。 。 。 .
不错 ReDoc 数据。 。 。 .
使用量
此插件需要额外的配置来使用, 参见 "配置" 如何配置生成文档的插件的一节.
以下是运行生成器的命令行选项:
serverless openapi generate [options]
选项
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 用于您服务中每个指定函数的事件区域.
此插件兼容同样的文档配置结构 无服务器锯入文档 并可以跑在旁边.
这个 custom 区域 serverless.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 现改为:
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)网站),描述了模型. 你们也可以:- 使用内线
YAML定义这些 - 使用无服务器的功能合并到外部 schema 文件
- 指定 json schema 的路径,在这种情况下, 如果您在多个 schemas 中重复使用某些类型 - 它们在生成的组件中将包含一次, 而不是重复每个 引用 schema
- 使用内线
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: 描述请求机构的模型清单(见 请求模式 (见下文)queryParams: 查询参数列表(参见 查询 (见下文)pathParams: 路径参数列表(参见 路径 (见下文)cookieParams: cookie 参数列表(参见 饼干 (见下文)methodResponses: 一系列反应模式和适用状态代码
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( 内含或文件)
queryParams:
- name: "filter"
description: "The filter parameter"
required: true
schema:
type: "string"
pathParams
路径参数可描述如下:
name: 查询变量的名称description: 查询变量描述schema: JSON schema( 内含或文件)
pathParams:
- name: "usernameId"
description: "The usernameId parameter"
schema:
type: "string"
cookieParams
Cookie 参数可描述如下:
name: 查询变量的名称description: 查询变量描述required: 查询参数是否为强制(布尔)schema: JSON schema( 内含或文件)
cookieParams:
- name: "sessionId"
description: "The sessionId parameter"
required: true
schema:
type: "string"
requestModels
这个 requestModels 属性允许您定义函数事件 HTTP 请求的模型。 您可以定义每个不同的模型 Content-Type。您可以定义在 models 区域 定义模式 页:1.
requestModels:
application/json: "CreateRequest"
application/xml: "CreateRequestXML"
methodResponses
您可以通过定义函数事件的属性来定义响应策略 .
举例来说 methodResponses 事件配置如下:
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 区域 定义模式 页:1.
responseModels:
application/json: "CreateResponse"
application/xml: "CreateResponseXML"
responseHeaders 财务报告和审定财务报表 requestHeaders
这个 responseHeaders/requestHeaders 区域配置允许您为函数事件定义 HTTP 标题.
信头的属性如下:
name: HTTP 页眉的名称description: HTTP 信头的描述schema: JSON schema( 内含或文件)
responseHeaders:
- name: "Content-Type"
description: "Content Type header"
schema:
type: "string"
requestHeaders:
- name: "Content-Type"
description: "Content Type header"
schema:
type: "string"
示例配置
请查看此示例 无服务器. yml。 。 。 .
安装
此插件适用于无服务器 1. x并上 。 无服务器 0. 5 不支持 .
要将此插件添加到您的软件包中。 json :
使用 npm :
npm install @conqa/serverless-openapi-documentation --save-dev
使用 Yarn :
yarn add @conqa/serverless-openapi-documentation --dev
您接下来需要将插件添加到 plugins 区域 serverless.yml 文档.
plugins:
- @conqa/serverless-openapi-documentation
您可以通过运行确认插件安装正确 :
serverless | grep -i "ServerlessOpenAPIDocumentation"
它应该回来了 ServerlessOpenAPIDocumentation 作为列表中的插件之一.
注意: 添加此插件 之后
serverless-offline防止出现问题String.replaceAll被错误地推翻.
许可证
麻省理工学院